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