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