docs/gst/tmpl/gstevent.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstEvent
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Structure describing events that are passed up and down a pipeline
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The event classes are used to construct and query events.
  10 </para>
  11
  12 <para>
  13 Events are usually created with gst_event_new() which takes the event type as an argument.
  14 properties specific to the event can be set afterwards with the provided macros.
  15 The event should be unreferenced with gst_event_unref().
  16 </para>
  17 <para>
  18 gst_event_new_seek() is a usually used to create a seek event and it takes the
  19 needed parameters for a seek event.
  20 </para>
  21 <para>
  22 gst_event_new_flush() creates a new flush event.
  23 </para>
  24
  25 <!-- ##### SECTION See_Also ##### -->
  26 <para>
  27 #GstPad, #GstElement
  28 </para>
  29
  30 <!-- ##### STRUCT GstEvent ##### -->
  31 <para>
  32
  33 </para>
  34
  35 @mini_object:
  36 @type:
  37 @timestamp:
  38 @src:
  39 @structure:
  40
  41 <!-- ##### ENUM GstEventType ##### -->
  42 <para>
  43 The different major types of events.
  44 </para>
  45
  46 @GST_EVENT_UNKNOWN: unknown event.
  47 @GST_EVENT_FLUSH_START:
  48 @GST_EVENT_FLUSH_STOP:
  49 @GST_EVENT_EOS: an end-of-stream event.
  50 @GST_EVENT_NEWSEGMENT:
  51 @GST_EVENT_TAG:
  52 @GST_EVENT_FILLER:
  53 @GST_EVENT_QOS: a quality of service event
  54 @GST_EVENT_SEEK: a seek event.
  55 @GST_EVENT_NAVIGATION:
  56 @GST_EVENT_CUSTOM_START:
  57
  58 <!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
  59 <para>
  60 The name used for memory allocation tracing
  61 </para>
  62
  63
  64
  65 <!-- ##### MACRO GST_EVENT_TYPE ##### -->
  66 <para>
  67 Get the event type.
  68 </para>
  69
  70 @event: The event to query.
  71
  72
  73 <!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
  74 <para>
  75 Get the timestamp of the event.
  76 </para>
  77
  78 @event: The event to query.
  79
  80
  81 <!-- ##### MACRO GST_EVENT_SRC ##### -->
  82 <para>
  83 The source object that generated this event
  84 </para>
  85
  86 @event: The event to query
  87
  88
  89 <!-- ##### ENUM GstSeekType ##### -->
  90 <para>
  91 The different types of seek events. When constructing a seek event a format,
  92 a seek method and optional flags are OR-ed together. The seek event is then
  93 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
  94
  95 Following example illustrates how to insert a seek event (1 second in the stream)
  96 in a pipeline.
  97 <example>
  98 <title>Insertion of a seek event into a pipeline</title>
  99   <programlisting>
 100   gboolean res;
 101   GstEvent *event;
 102
 103   event = gst_event_new_seek (
 104             GST_FORMAT_TIME |           /* seek on time */
 105             GST_SEEK_METHOD_SET |       /* set the absolute position */
 106             GST_SEEK_FLAG_FLUSH,        /* flush any pending data */
 107             1 * GST_SECOND);            /* the seek offset (1 second) */
 108
 109   res = gst_element_send_event (GST_ELEMENT (osssink), event);
 110   if (!res) {
 111     g_warning ("seek failed");
 112   }
 113   </programlisting>
 114 </example>
 115 </para>
 116
 117 @GST_SEEK_TYPE_NONE:
 118 @GST_SEEK_TYPE_CUR:
 119 @GST_SEEK_TYPE_SET:
 120 @GST_SEEK_TYPE_END:
 121
 122 <!-- ##### MACRO gst_event_ref ##### -->
 123 <para>
 124 Increase the refcount of this event
 125 </para>
 126
 127 @ev: The event to refcount
 128
 129
 130 <!-- ##### MACRO gst_event_unref ##### -->
 131 <para>
 132 Decrease the refcount of an event, freeing it if the refcount reaches 0
 133 </para>
 134
 135 @ev: The event to unref
 136
 137
 138 <!-- ##### MACRO gst_event_copy ##### -->
 139 <para>
 140 Copy the event using the event specific copy function
 141 </para>
 142
 143 @ev: The event to copy
 144 @Returns: A new event that is a copy of the given input event
 145
 146
 147 <!-- ##### FUNCTION gst_event_new_custom ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @type:
 153 @structure:
 154 @Returns:
 155
 156
 157 <!-- ##### FUNCTION gst_event_get_structure ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @event:
 163 @Returns:
 164
 165
 166 <!-- ##### FUNCTION gst_event_new_flush_start ##### -->
 167 <para>
 168
 169 </para>
 170
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION gst_event_new_flush_stop ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @Returns:
 180
 181
 182 <!-- ##### FUNCTION gst_event_new_eos ##### -->
 183 <para>
 184
 185 </para>
 186
 187 @Returns:
 188
 189
 190 <!-- ##### FUNCTION gst_event_new_newsegment ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @rate:
 196 @format:
 197 @start_value:
 198 @stop_value:
 199 @base:
 200 @Returns:
 201
 202
 203 <!-- ##### FUNCTION gst_event_parse_newsegment ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @event:
 209 @rate:
 210 @format:
 211 @start_value:
 212 @end_value:
 213 @base:
 214
 215
 216 <!-- ##### FUNCTION gst_event_new_tag ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @taglist:
 222 @Returns:
 223
 224
 225 <!-- ##### FUNCTION gst_event_parse_tag ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @event:
 231 @taglist:
 232
 233
 234 <!-- ##### FUNCTION gst_event_new_filler ##### -->
 235 <para>
 236 Create a new dummy event that should be ignored
 237 </para>
 238
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION gst_event_new_qos ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @proportion:
 248 @diff:
 249 @timestamp:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION gst_event_parse_qos ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @event:
 259 @proportion:
 260 @diff:
 261 @timestamp:
 262
 263
 264 <!-- ##### FUNCTION gst_event_new_seek ##### -->
 265 <para>
 266
 267 </para>
 268
 269 @rate:
 270 @format:
 271 @flags:
 272 @cur_type:
 273 @cur:
 274 @stop_type:
 275 @stop:
 276 @Returns:
 277 <!-- # Unused Parameters # -->
 278 @type:
 279 @offset:
 280
 281
 282 <!-- ##### FUNCTION gst_event_parse_seek ##### -->
 283 <para>
 284
 285 </para>
 286
 287 @event:
 288 @rate:
 289 @format:
 290 @flags:
 291 @cur_type:
 292 @cur:
 293 @stop_type:
 294 @stop:
 295
 296
 297 <!-- ##### FUNCTION gst_event_new_navigation ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @structure:
 303 @Returns:
 304
 305