docs/gst/tmpl/gstevent.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstEvent
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Event definitions.
   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 <!-- ##### ENUM GstEventType ##### -->
  31 <para>
  32 The different major types of events.
  33 </para>
  34
  35 @GST_EVENT_UNKNOWN: unknown event.
  36 @GST_EVENT_EOS: an end-of-stream event.
  37 @GST_EVENT_FLUSH: a flush event.
  38 @GST_EVENT_EMPTY: an empty event.
  39 @GST_EVENT_DISCONTINUOUS: a discontinuous event to indicate the stream has a discontinuity.
  40 @GST_EVENT_QOS: a quality of service event
  41 @GST_EVENT_SEEK: a seek event.
  42 @GST_EVENT_SEEK_SEGMENT: a segment seek with start and stop position
  43 @GST_EVENT_SEGMENT_DONE: the event that will be emited when the segment seek has ended
  44 @GST_EVENT_SIZE: a size suggestion for a peer element
  45 @GST_EVENT_RATE: adjust the output rate of an element
  46 @GST_EVENT_FILLER: a dummy event that should be ignored by plugins
  47 @GST_EVENT_TS_OFFSET: an event to set the time offset on buffers
  48 @GST_EVENT_INTERRUPT: mainly used by _get based elements when they were interrupted
  49                       while waiting for a buffer.
  50
  51 <!-- ##### MACRO GST_EVENT_TYPE ##### -->
  52 <para>
  53 Get the event type.
  54 </para>
  55
  56 @event: The event to query.
  57
  58
  59 <!-- ##### MACRO GST_EVENT_SRC ##### -->
  60 <para>
  61 The source object that generated this event
  62 </para>
  63
  64 @event: The event to query
  65
  66
  67 <!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
  68 <para>
  69 Get the timestamp of the event.
  70 </para>
  71
  72 @event: The event to query.
  73
  74
  75 <!-- ##### ENUM GstEventFlag ##### -->
  76 <para>
  77 Event flags are used when querying for supported events
  78 </para>
  79
  80 @GST_EVENT_FLAG_NONE: no value
  81 @GST_RATE_FLAG_NEGATIVE: indicates negative rates are supported
  82
  83 <!-- ##### ENUM GstSeekType ##### -->
  84 <para>
  85 The different types of seek events. When constructing a seek event a format,
  86 a seek method and optional flags are OR-ed together. The seek event is then
  87 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
  88
  89  <informalexample>
  90   Following example illustrates how to insert a seek event (1 second in the stream)
  91   in a pipeline.
  92
  93   <programlisting>
  94   gboolean res;
  95   GstEvent *event;
  96
  97   event = gst_event_new_seek (
  98             GST_FORMAT_TIME |           /* seek on time */
  99             GST_SEEK_METHOD_SET |       /* set the absolute position */
 100             GST_SEEK_FLAG_FLUSH,        /* flush any pending data */
 101             1 * GST_SECOND);            /* the seek offset (1 second) */
 102
 103   res = gst_element_send_event (GST_ELEMENT (osssink), event);
 104   if (!res) {
 105     g_warning ("seek failed");
 106   }
 107   </programlisting>
 108  </informalexample>
 109 </para>
 110
 111 @GST_SEEK_METHOD_CUR: Seek to an relative position
 112 @GST_SEEK_METHOD_SET: Seek to an absolute position
 113 @GST_SEEK_METHOD_END: Seek relative to the end of the stream
 114 @GST_SEEK_FLAG_FLUSH: Flush any pending data while seeking
 115 @GST_SEEK_FLAG_ACCURATE: Seek as accuratly as possible
 116 @GST_SEEK_FLAG_KEY_UNIT: Seek to a nearby key unit
 117 @GST_SEEK_FLAG_SEGMENT_LOOP: Loop between start and stop in a segmented seek
 118
 119 <!-- ##### ENUM GstSeekAccuracy ##### -->
 120 <para>
 121 The seekaccuracy gives more information of how the seek was performed,
 122 if the seek was accurate or fuzzy.
 123 </para>
 124
 125 @GST_SEEK_CERTAIN: The seek was exact
 126 @GST_SEEK_FUZZY: The seek was fuzzy, exact position can not be guaranteed
 127
 128 <!-- ##### MACRO GST_EVENT_SEEK_TYPE ##### -->
 129 <para>
 130 Get the seektype of the GST_EVENT_SEEK.
 131 </para>
 132
 133 @event: The event to query.
 134
 135
 136 <!-- ##### MACRO GST_EVENT_SEEK_FORMAT ##### -->
 137 <para>
 138 The format of the seek value
 139 </para>
 140
 141 @event: The event operate on
 142
 143
 144 <!-- ##### MACRO GST_EVENT_SEEK_METHOD ##### -->
 145 <para>
 146 The seek method to use as one of #GstSeekType
 147 </para>
 148
 149 @event: The event operate on
 150
 151
 152 <!-- ##### MACRO GST_EVENT_SEEK_FLAGS ##### -->
 153 <para>
 154 The optional seek flags
 155 </para>
 156
 157 @event: The event operate on
 158
 159
 160 <!-- ##### MACRO GST_EVENT_SEEK_OFFSET ##### -->
 161 <para>
 162 Get the offset of the seek event.
 163 </para>
 164
 165 @event: The event to query.
 166
 167
 168 <!-- ##### MACRO GST_EVENT_SEEK_ACCURACY ##### -->
 169 <para>
 170 Indicates how accurate the event was performed.
 171 </para>
 172
 173 @event: The event to query
 174
 175
 176 <!-- ##### MACRO GST_SEEK_FLAGS_MASK ##### -->
 177 <para>
 178 Mask for the flags in the GstSeekType
 179 </para>
 180
 181
 182
 183 <!-- ##### MACRO GST_SEEK_FLAGS_SHIFT ##### -->
 184 <para>
 185 Shift for the flags in the GstSeekType
 186 </para>
 187
 188
 189
 190 <!-- ##### MACRO GST_SEEK_FORMAT_MASK ##### -->
 191 <para>
 192 Mask for the format in the GstSeekType
 193 </para>
 194
 195
 196
 197 <!-- ##### MACRO GST_SEEK_FORMAT_SHIFT ##### -->
 198 <para>
 199 Shift for the format in the GstSeekType
 200 </para>
 201
 202
 203
 204 <!-- ##### MACRO GST_SEEK_METHOD_MASK ##### -->
 205 <para>
 206 Mask for the method in the GstSeekType
 207 </para>
 208
 209
 210
 211 <!-- ##### MACRO GST_SEEK_METHOD_SHIFT ##### -->
 212 <para>
 213 Shift for the method in the GstSeekType
 214 </para>
 215
 216
 217
 218 <!-- ##### MACRO GST_EVENT_DISCONT_NEW_MEDIA ##### -->
 219 <para>
 220 Flag that indicates the discont event was because of a new media
 221 type.
 222 </para>
 223
 224 @event: The event to operate on
 225
 226
 227 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET ##### -->
 228 <para>
 229 The offset of the discont event. A discont evetn can hold up to 8 different
 230 format/value pairs.
 231 </para>
 232
 233 @event: The event to query
 234 @i: The offset/value pair.
 235
 236
 237 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET_LEN ##### -->
 238 <para>
 239 Get the number of offset/value pairs this event has.
 240 </para>
 241
 242 @event: The event to query.
 243
 244
 245 <!-- ##### MACRO GST_EVENT_RATE_VALUE ##### -->
 246 <para>
 247 Get access to the rate vale field
 248 </para>
 249
 250 @event: The event to query
 251
 252
 253 <!-- ##### MACRO GST_EVENT_SEEK_ENDOFFSET ##### -->
 254 <para>
 255 The event stop position for a segment seek
 256 </para>
 257
 258 @event: The event to query
 259
 260
 261 <!-- ##### MACRO GST_EVENT_SIZE_FORMAT ##### -->
 262 <para>
 263 The format of the size event.
 264 </para>
 265
 266 @event: The event to query
 267
 268
 269 <!-- ##### MACRO GST_EVENT_SIZE_VALUE ##### -->
 270 <para>
 271 The value of the size event
 272 </para>
 273
 274 @event: The event to query
 275
 276
 277 <!-- ##### MACRO GST_EVENT_IS_INTERRUPT ##### -->
 278 <para>
 279 Check if the event is an interrupt event
 280 </para>
 281
 282 @event: The event to check
 283
 284
 285 <!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
 286 <para>
 287 The name used for memory allocation tracing
 288 </para>
 289
 290
 291
 292 <!-- ##### STRUCT GstEvent ##### -->
 293 <para>
 294 The event structure
 295 </para>
 296
 297 @data:
 298 @type:
 299 @timestamp:
 300 @src:
 301
 302 <!-- ##### FUNCTION gst_event_new ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @type:
 308 @Returns:
 309
 310
 311 <!-- ##### MACRO gst_event_copy ##### -->
 312 <para>
 313 Copy the event using the event specific copy function
 314 </para>
 315
 316 @ev: The event to copy
 317 @Returns: A new event that is a copy of the given input event
 318
 319
 320 <!-- ##### MACRO gst_event_ref ##### -->
 321 <para>
 322 Increase the refcount of this event
 323 </para>
 324
 325 @ev: The event to refcount
 326
 327
 328 <!-- ##### MACRO gst_event_ref_by_count ##### -->
 329 <para>
 330 Increase the refcount of the event with the given value
 331 </para>
 332
 333 @ev: The event to refcount
 334 @c: The value to add to the refcount
 335
 336
 337 <!-- ##### MACRO gst_event_unref ##### -->
 338 <para>
 339 Decrease the refcount of an event, freeing it if the refcount reaches 0
 340 </para>
 341
 342 @ev: The event to unref
 343
 344
 345 <!-- ##### FUNCTION gst_event_new_seek ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @type:
 351 @offset:
 352 @Returns:
 353
 354
 355 <!-- ##### FUNCTION gst_event_new_segment_seek ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @type:
 361 @start:
 362 @stop:
 363 @Returns:
 364
 365
 366 <!-- ##### FUNCTION gst_event_new_size ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @format:
 372 @value:
 373 @Returns:
 374
 375
 376 <!-- ##### FUNCTION gst_event_new_discontinuous ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @new_media:
 382 @format1:
 383 @Varargs:
 384 @Returns:
 385
 386
 387 <!-- ##### FUNCTION gst_event_discont_get_value ##### -->
 388 <para>
 389
 390 </para>
 391
 392 @event:
 393 @format:
 394 @value:
 395 @Returns:
 396
 397
 398 <!-- ##### MACRO gst_event_new_filler ##### -->
 399 <para>
 400 Create a new dummy event that should be ignored
 401 </para>
 402
 403
 404
 405 <!-- ##### MACRO gst_event_new_flush ##### -->
 406 <para>
 407 Create a new flush event.
 408 </para>
 409
 410
 411
 412 <!-- ##### FUNCTION gst_event_masks_contains ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @masks:
 418 @mask:
 419 @Returns:
 420
 421
 422 <!-- ##### MACRO GST_EVENT_MASK_FUNCTION ##### -->
 423 <para>
 424 A convenience macro to create event mask functions
 425 </para>
 426
 427 @type: The type of the first argument of the function
 428 @functionname: the name of the function
 429 @...: event masks, the last element is marked with 0
 430
 431