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