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 @data:
  36 @type:
  37 @timestamp:
  38 @src:
  39
  40 <!-- ##### ENUM GstEventType ##### -->
  41 <para>
  42 The different major types of events.
  43 </para>
  44
  45 @GST_EVENT_UNKNOWN: unknown event.
  46 @GST_EVENT_EOS: an end-of-stream event.
  47 @GST_EVENT_FLUSH: a flush event.
  48 @GST_EVENT_EMPTY: an empty event.
  49 @GST_EVENT_DISCONTINUOUS: a discontinuous event to indicate the stream has a discontinuity.
  50 @GST_EVENT_QOS: a quality of service event
  51 @GST_EVENT_SEEK: a seek event.
  52 @GST_EVENT_SEEK_SEGMENT: a segment seek with start and stop position
  53 @GST_EVENT_SEGMENT_DONE: the event that will be emited when the segment seek has ended
  54 @GST_EVENT_SIZE: a size suggestion for a peer element
  55 @GST_EVENT_RATE: adjust the output rate of an element
  56 @GST_EVENT_FILLER: a dummy event that should be ignored by plugins
  57 @GST_EVENT_TS_OFFSET: an event to set the time offset on buffers
  58 @GST_EVENT_INTERRUPT: mainly used by _get based elements when they were interrupted
  59                       while waiting for a buffer.
  60 @GST_EVENT_NAVIGATION:
  61 @GST_EVENT_TAG:
  62
  63 <!-- ##### MACRO GST_EVENT_ANY ##### -->
  64 <para>
  65
  66 </para>
  67
  68
  69
  70 <!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
  71 <para>
  72 The name used for memory allocation tracing
  73 </para>
  74
  75
  76
  77 <!-- ##### MACRO GST_EVENT_TYPE ##### -->
  78 <para>
  79 Get the event type.
  80 </para>
  81
  82 @event: The event to query.
  83
  84
  85 <!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
  86 <para>
  87 Get the timestamp of the event.
  88 </para>
  89
  90 @event: The event to query.
  91
  92
  93 <!-- ##### MACRO GST_EVENT_SRC ##### -->
  94 <para>
  95 The source object that generated this event
  96 </para>
  97
  98 @event: The event to query
  99
 100
 101 <!-- ##### MACRO GST_EVENT_IS_INTERRUPT ##### -->
 102 <para>
 103 Check if the event is an interrupt event
 104 </para>
 105
 106 @event: The event to check
 107
 108
 109 <!-- ##### MACRO GST_SEEK_FORMAT_SHIFT ##### -->
 110 <para>
 111 Shift for the format in the GstSeekType
 112 </para>
 113
 114
 115
 116 <!-- ##### MACRO GST_SEEK_METHOD_SHIFT ##### -->
 117 <para>
 118 Shift for the method in the GstSeekType
 119 </para>
 120
 121
 122
 123 <!-- ##### MACRO GST_SEEK_FLAGS_SHIFT ##### -->
 124 <para>
 125 Shift for the flags in the GstSeekType
 126 </para>
 127
 128
 129
 130 <!-- ##### MACRO GST_SEEK_FORMAT_MASK ##### -->
 131 <para>
 132 Mask for the format in the GstSeekType
 133 </para>
 134
 135
 136
 137 <!-- ##### MACRO GST_SEEK_METHOD_MASK ##### -->
 138 <para>
 139 Mask for the method in the GstSeekType
 140 </para>
 141
 142
 143
 144 <!-- ##### MACRO GST_SEEK_FLAGS_MASK ##### -->
 145 <para>
 146 Mask for the flags in the GstSeekType
 147 </para>
 148
 149
 150
 151 <!-- ##### ENUM GstEventFlag ##### -->
 152 <para>
 153 Event flags are used when querying for supported events
 154 </para>
 155
 156 @GST_EVENT_FLAG_NONE: no value
 157 @GST_RATE_FLAG_NEGATIVE: indicates negative rates are supported
 158
 159 <!-- ##### MACRO GST_EVENT_MASK_FUNCTION ##### -->
 160 <para>
 161 A convenience macro to create event mask functions
 162 </para>
 163
 164 @type: The type of the first argument of the function
 165 @functionname: the name of the function
 166 @...: event masks, the last element is marked with 0
 167
 168
 169 <!-- ##### ENUM GstSeekType ##### -->
 170 <para>
 171 The different types of seek events. When constructing a seek event a format,
 172 a seek method and optional flags are OR-ed together. The seek event is then
 173 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
 174
 175 Following example illustrates how to insert a seek event (1 second in the stream)
 176 in a pipeline.
 177 <example>
 178 <title>Insertion of a seek event into a pipeline</title>
 179   <programlisting>
 180   gboolean res;
 181   GstEvent *event;
 182
 183   event = gst_event_new_seek (
 184             GST_FORMAT_TIME |           /* seek on time */
 185             GST_SEEK_METHOD_SET |       /* set the absolute position */
 186             GST_SEEK_FLAG_FLUSH,        /* flush any pending data */
 187             1 * GST_SECOND);            /* the seek offset (1 second) */
 188
 189   res = gst_element_send_event (GST_ELEMENT (osssink), event);
 190   if (!res) {
 191     g_warning ("seek failed");
 192   }
 193   </programlisting>
 194 </example>
 195 </para>
 196
 197 @GST_SEEK_METHOD_CUR: Seek to an relative position
 198 @GST_SEEK_METHOD_SET: Seek to an absolute position
 199 @GST_SEEK_METHOD_END: Seek relative to the end of the stream
 200 @GST_SEEK_FLAG_FLUSH: Flush any pending data while seeking
 201 @GST_SEEK_FLAG_ACCURATE: Seek as accurately as possible
 202 @GST_SEEK_FLAG_KEY_UNIT: Seek to a nearby key unit
 203 @GST_SEEK_FLAG_SEGMENT_LOOP: Loop between start and stop in a segmented seek
 204
 205 <!-- ##### ENUM GstSeekAccuracy ##### -->
 206 <para>
 207 The accuracy about a seek operation gives more information of how the seek was
 208 performed, namly if the seek was accurate or fuzzy.
 209 </para>
 210
 211 @GST_SEEK_CERTAIN: The seek was exact
 212 @GST_SEEK_FUZZY: The seek was fuzzy, exact position can not be guaranteed
 213
 214 <!-- ##### MACRO GST_EVENT_SEEK_TYPE ##### -->
 215 <para>
 216 Get the seektype of the GST_EVENT_SEEK.
 217 </para>
 218
 219 @event: The event to query.
 220
 221
 222 <!-- ##### MACRO GST_EVENT_SEEK_FORMAT ##### -->
 223 <para>
 224 The format of the seek value
 225 </para>
 226
 227 @event: The event operate on
 228
 229
 230 <!-- ##### MACRO GST_EVENT_SEEK_METHOD ##### -->
 231 <para>
 232 The seek method to use as one of #GstSeekType
 233 </para>
 234
 235 @event: The event operate on
 236
 237
 238 <!-- ##### MACRO GST_EVENT_SEEK_FLAGS ##### -->
 239 <para>
 240 The optional seek flags
 241 </para>
 242
 243 @event: The event operate on
 244
 245
 246 <!-- ##### MACRO GST_EVENT_SEEK_OFFSET ##### -->
 247 <para>
 248 Get the offset of the seek event.
 249 </para>
 250
 251 @event: The event to query.
 252
 253
 254 <!-- ##### MACRO GST_EVENT_SEEK_ENDOFFSET ##### -->
 255 <para>
 256 The event stop position for a segment seek
 257 </para>
 258
 259 @event: The event to query
 260
 261
 262 <!-- ##### MACRO GST_EVENT_SEEK_ACCURACY ##### -->
 263 <para>
 264 Indicates how accurate the event was performed.
 265 </para>
 266
 267 @event: The event to query
 268
 269
 270 <!-- ##### MACRO GST_EVENT_DISCONT_NEW_MEDIA ##### -->
 271 <para>
 272 Flag that indicates the discont event was because of a new media
 273 type.
 274 </para>
 275
 276 @event: The event to operate on
 277
 278
 279 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET ##### -->
 280 <para>
 281 The offset of the discont event. A discont event can hold up to 8 different
 282 format/value pairs.
 283 </para>
 284
 285 @event: The event to query
 286 @i: The offset/value pair.
 287
 288
 289 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET_LEN ##### -->
 290 <para>
 291 Get the number of offset/value pairs this event has.
 292 </para>
 293
 294 @event: The event to query.
 295
 296
 297 <!-- ##### MACRO GST_EVENT_SIZE_FORMAT ##### -->
 298 <para>
 299 The format of the size event.
 300 </para>
 301
 302 @event: The event to query
 303
 304
 305 <!-- ##### MACRO GST_EVENT_SIZE_VALUE ##### -->
 306 <para>
 307 The value of the size event
 308 </para>
 309
 310 @event: The event to query
 311
 312
 313 <!-- ##### MACRO GST_EVENT_RATE_VALUE ##### -->
 314 <para>
 315 Get access to the rate vale field
 316 </para>
 317
 318 @event: The event to query
 319
 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