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