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