1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gstreamer.Event; 26 27 private import glib.ConstructionException; 28 private import glib.Str; 29 private import gobject.ObjectG; 30 private import gstreamer.Buffer; 31 private import gstreamer.Caps; 32 private import gstreamer.Message; 33 private import gstreamer.Segment; 34 private import gstreamer.Structure; 35 private import gstreamer.TagList; 36 private import gstreamer.Toc; 37 private import gstreamerc.gstreamer; 38 public import gstreamerc.gstreamertypes; 39 40 41 /** 42 * The event class provides factory methods to construct events for sending 43 * and functions to query (parse) received events. 44 * 45 * Events are usually created with gst_event_new_*() which takes event-type 46 * specific parameters as arguments. 47 * To send an event application will usually use gst_element_send_event() and 48 * elements will use gst_pad_send_event() or gst_pad_push_event(). 49 * The event should be unreffed with gst_event_unref() if it has not been sent. 50 * 51 * Events that have been received can be parsed with their respective 52 * gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details. 53 * 54 * Events are passed between elements in parallel to the data stream. Some events 55 * are serialized with buffers, others are not. Some events only travel downstream, 56 * others only upstream. Some events can travel both upstream and downstream. 57 * 58 * The events are used to signal special conditions in the datastream such as 59 * EOS (end of stream) or the start of a new stream-segment. 60 * Events are also used to flush the pipeline of any pending data. 61 * 62 * Most of the event API is used inside plugins. Applications usually only 63 * construct and use seek events. 64 * To do that gst_event_new_seek() is used to create a seek event. It takes 65 * the needed parameters to specify seeking time and mode. 66 * |[<!-- language="C" --> 67 * GstEvent *event; 68 * gboolean result; 69 * ... 70 * // construct a seek event to play the media from second 2 to 5, flush 71 * // the pipeline to decrease latency. 72 * event = gst_event_new_seek (1.0, 73 * GST_FORMAT_TIME, 74 * GST_SEEK_FLAG_FLUSH, 75 * GST_SEEK_TYPE_SET, 2 * GST_SECOND, 76 * GST_SEEK_TYPE_SET, 5 * GST_SECOND); 77 * ... 78 * result = gst_element_send_event (pipeline, event); 79 * if (!result) 80 * g_warning ("seek failed"); 81 * ... 82 * ]| 83 */ 84 public class Event 85 { 86 /** the main Gtk struct */ 87 protected GstEvent* gstEvent; 88 protected bool ownedRef; 89 90 /** Get the main Gtk struct */ 91 public GstEvent* getEventStruct() 92 { 93 return gstEvent; 94 } 95 96 /** the main Gtk struct as a void* */ 97 protected void* getStruct() 98 { 99 return cast(void*)gstEvent; 100 } 101 102 /** 103 * Sets our main struct and passes it to the parent class. 104 */ 105 public this (GstEvent* gstEvent, bool ownedRef = false) 106 { 107 this.gstEvent = gstEvent; 108 this.ownedRef = ownedRef; 109 } 110 111 /** 112 * Create a new EOS event. The eos event can only travel downstream 113 * synchronized with the buffer flow. Elements that receive the EOS 114 * event on a pad can return UNEXPECTED as a GstFlowReturn when data 115 * after the EOS event arrives. 116 * The EOS event will travel down to the sink elements in the pipeline 117 * which will then post the GST_MESSAGE_EOS on the bus after they have 118 * finished playing any buffered data. 119 * When all sinks have posted an EOS message, the EOS message is 120 * forwarded to the application. 121 * Returns: 122 * The new EOS event. 123 */ 124 public static Event newEOS() 125 { 126 // GstEvent* gst_event_new_eos (void); 127 auto p = gst_event_new_eos(); 128 129 if(p is null) 130 { 131 throw new ConstructionException("null returned by gst_event_new_eos"); 132 } 133 134 return new Event(cast(GstEvent*)p ); 135 } 136 137 /** 138 * Allocate a new flush start event. The flush start event can be send 139 * upstream and downstream and travels out-of-bounds with the dataflow. 140 * It marks pads as being in a WRONG_STATE to process more data. 141 * Elements unlock and blocking functions and exit their streaming functions 142 * as fast as possible. 143 * This event is typically generated after a seek to minimize the latency 144 * after the seek. 145 * Returns: 146 * A new flush start event. 147 */ 148 public static Event newFlushStart() 149 { 150 // GstEvent* gst_event_new_flush_start (void); 151 auto p = gst_event_new_flush_start(); 152 153 if(p is null) 154 { 155 throw new ConstructionException("null returned by gst_event_new_flush_start"); 156 } 157 158 return new Event(cast(GstEvent*)p ); 159 } 160 161 /** 162 * Generate a TOC select event with the given uid. The purpose of the 163 * TOC select event is to start playback based on the TOC's entry with 164 * the given uid. 165 */ 166 public static Event newTocSelect(string uid) 167 { 168 // GstEvent* gst_event_new_toc_select (const gchar *uid); 169 auto p = gst_event_new_toc_select(cast(char*)uid.ptr); 170 171 if(p is null) 172 { 173 throw new ConstructionException("null returned by gst_event_new_toc_select"); 174 } 175 176 return new Event(cast(GstEvent*)p ); 177 } 178 179 /** 180 */ 181 182 /** */ 183 public static GType getType() 184 { 185 return gst_event_get_type(); 186 } 187 188 /** 189 * Create a new buffersize event. The event is sent downstream and notifies 190 * elements that they should provide a buffer of the specified dimensions. 191 * 192 * When the @async flag is set, a thread boundary is preferred. 193 * 194 * Params: 195 * format = buffer format 196 * minsize = minimum buffer size 197 * maxsize = maximum buffer size 198 * async = thread behavior 199 * 200 * Return: a new #GstEvent 201 * 202 * Throws: ConstructionException GTK+ fails to create the object. 203 */ 204 public this(GstFormat format, long minsize, long maxsize, bool async) 205 { 206 auto p = gst_event_new_buffer_size(format, minsize, maxsize, async); 207 208 if(p is null) 209 { 210 throw new ConstructionException("null returned by new_buffer_size"); 211 } 212 213 this(cast(GstEvent*) p); 214 } 215 216 /** 217 * Create a new CAPS event for @caps. The caps event can only travel downstream 218 * synchronized with the buffer flow and contains the format of the buffers 219 * that will follow after the event. 220 * 221 * Params: 222 * caps = a #GstCaps 223 * 224 * Return: the new CAPS event. 225 * 226 * Throws: ConstructionException GTK+ fails to create the object. 227 */ 228 public this(Caps caps) 229 { 230 auto p = gst_event_new_caps((caps is null) ? null : caps.getCapsStruct()); 231 232 if(p is null) 233 { 234 throw new ConstructionException("null returned by new_caps"); 235 } 236 237 this(cast(GstEvent*) p); 238 } 239 240 /** 241 * Create a new custom-typed event. This can be used for anything not 242 * handled by other event-specific functions to pass an event to another 243 * element. 244 * 245 * Make sure to allocate an event type with the #GST_EVENT_MAKE_TYPE macro, 246 * assigning a free number and filling in the correct direction and 247 * serialization flags. 248 * 249 * New custom events can also be created by subclassing the event type if 250 * needed. 251 * 252 * Params: 253 * type = The type of the new event 254 * structure = the structure for the event. The event will 255 * take ownership of the structure. 256 * 257 * Return: the new custom event. 258 * 259 * Throws: ConstructionException GTK+ fails to create the object. 260 */ 261 public this(GstEventType type, Structure structure) 262 { 263 auto p = gst_event_new_custom(type, (structure is null) ? null : structure.getStructureStruct()); 264 265 if(p is null) 266 { 267 throw new ConstructionException("null returned by new_custom"); 268 } 269 270 this(cast(GstEvent*) p); 271 } 272 273 /** 274 * Allocate a new flush stop event. The flush stop event can be sent 275 * upstream and downstream and travels serialized with the dataflow. 276 * It is typically sent after sending a FLUSH_START event to make the 277 * pads accept data again. 278 * 279 * Elements can process this event synchronized with the dataflow since 280 * the preceding FLUSH_START event stopped the dataflow. 281 * 282 * This event is typically generated to complete a seek and to resume 283 * dataflow. 284 * 285 * Params: 286 * resetTime = if time should be reset 287 * 288 * Return: a new flush stop event. 289 * 290 * Throws: ConstructionException GTK+ fails to create the object. 291 */ 292 public this(bool resetTime) 293 { 294 auto p = gst_event_new_flush_stop(resetTime); 295 296 if(p is null) 297 { 298 throw new ConstructionException("null returned by new_flush_stop"); 299 } 300 301 this(cast(GstEvent*) p); 302 } 303 304 /** 305 * Create a new GAP event. A gap event can be thought of as conceptually 306 * equivalent to a buffer to signal that there is no data for a certain 307 * amount of time. This is useful to signal a gap to downstream elements 308 * which may wait for data, such as muxers or mixers or overlays, especially 309 * for sparse streams such as subtitle streams. 310 * 311 * Params: 312 * timestamp = the start time (pts) of the gap 313 * duration = the duration of the gap 314 * 315 * Return: the new GAP event. 316 * 317 * Throws: ConstructionException GTK+ fails to create the object. 318 */ 319 public this(GstClockTime timestamp, GstClockTime duration) 320 { 321 auto p = gst_event_new_gap(timestamp, duration); 322 323 if(p is null) 324 { 325 throw new ConstructionException("null returned by new_gap"); 326 } 327 328 this(cast(GstEvent*) p); 329 } 330 331 /** 332 * Create a new latency event. The event is sent upstream from the sinks and 333 * notifies elements that they should add an additional @latency to the 334 * running time before synchronising against the clock. 335 * 336 * The latency is mostly used in live sinks and is always expressed in 337 * the time format. 338 * 339 * Params: 340 * latency = the new latency value 341 * 342 * Return: a new #GstEvent 343 * 344 * Throws: ConstructionException GTK+ fails to create the object. 345 */ 346 public this(GstClockTime latency) 347 { 348 auto p = gst_event_new_latency(latency); 349 350 if(p is null) 351 { 352 throw new ConstructionException("null returned by new_latency"); 353 } 354 355 this(cast(GstEvent*) p); 356 } 357 358 /** 359 * Create a new navigation event from the given description. 360 * 361 * Params: 362 * structure = description of the event. The event will take 363 * ownership of the structure. 364 * 365 * Return: a new #GstEvent 366 * 367 * Throws: ConstructionException GTK+ fails to create the object. 368 */ 369 public this(Structure structure) 370 { 371 auto p = gst_event_new_navigation((structure is null) ? null : structure.getStructureStruct()); 372 373 if(p is null) 374 { 375 throw new ConstructionException("null returned by new_navigation"); 376 } 377 378 this(cast(GstEvent*) p); 379 } 380 381 /** 382 * Creates a new event containing information specific to a particular 383 * protection system (uniquely identified by @system_id), by which that 384 * protection system can acquire key(s) to decrypt a protected stream. 385 * 386 * In order for a decryption element to decrypt media 387 * protected using a specific system, it first needs all the 388 * protection system specific information necessary to acquire the decryption 389 * key(s) for that stream. The functions defined here enable this information 390 * to be passed in events from elements that extract it 391 * (e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter 392 * elements that use it. 393 * 394 * Events containing protection system specific information are created using 395 * #gst_event_new_protection, and they can be parsed by downstream elements 396 * using #gst_event_parse_protection. 397 * 398 * In Common Encryption, protection system specific information may be located 399 * within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) 400 * boxes; it may also be contained in ContentProtection elements within MPEG 401 * DASH MPDs. The events created by #gst_event_new_protection contain data 402 * identifying from which of these locations the encapsulated protection system 403 * specific information originated. This origin information is required as 404 * some protection systems use different encodings depending upon where the 405 * information originates. 406 * 407 * The events returned by gst_event_new_protection() are implemented 408 * in such a way as to ensure that the most recently-pushed protection info 409 * event of a particular @origin and @system_id will 410 * be stuck to the output pad of the sending element. 411 * 412 * Params: 413 * systemId = a string holding a UUID that uniquely 414 * identifies a protection system. 415 * data = a #GstBuffer holding protection system specific 416 * information. The reference count of the buffer will be incremented by one. 417 * origin = a string indicating where the protection 418 * information carried in the event was extracted from. The allowed values 419 * of this string will depend upon the protection scheme. 420 * 421 * Return: a #GST_EVENT_PROTECTION event, if successful; %NULL 422 * if unsuccessful. 423 * 424 * Since: 1.6 425 * 426 * Throws: ConstructionException GTK+ fails to create the object. 427 */ 428 public this(string systemId, Buffer data, string origin) 429 { 430 auto p = gst_event_new_protection(Str.toStringz(systemId), (data is null) ? null : data.getBufferStruct(), Str.toStringz(origin)); 431 432 if(p is null) 433 { 434 throw new ConstructionException("null returned by new_protection"); 435 } 436 437 this(cast(GstEvent*) p); 438 } 439 440 /** 441 * Allocate a new qos event with the given values. 442 * The QOS event is generated in an element that wants an upstream 443 * element to either reduce or increase its rate because of 444 * high/low CPU load or other resource usage such as network performance or 445 * throttling. Typically sinks generate these events for each buffer 446 * they receive. 447 * 448 * @type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is 449 * used when a buffer arrived in time or when the sink cannot keep up with 450 * the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not 451 * receiving buffers fast enough and thus has to drop late buffers. 452 * #GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited 453 * by the application, for example to reduce power consumption. 454 * 455 * @proportion indicates the real-time performance of the streaming in the 456 * element that generated the QoS event (usually the sink). The value is 457 * generally computed based on more long term statistics about the streams 458 * timestamps compared to the clock. 459 * A value < 1.0 indicates that the upstream element is producing data faster 460 * than real-time. A value > 1.0 indicates that the upstream element is not 461 * producing data fast enough. 1.0 is the ideal @proportion value. The 462 * proportion value can safely be used to lower or increase the quality of 463 * the element. 464 * 465 * @diff is the difference against the clock in running time of the last 466 * buffer that caused the element to generate the QOS event. A negative value 467 * means that the buffer with @timestamp arrived in time. A positive value 468 * indicates how late the buffer with @timestamp was. When throttling is 469 * enabled, @diff will be set to the requested throttling interval. 470 * 471 * @timestamp is the timestamp of the last buffer that cause the element 472 * to generate the QOS event. It is expressed in running time and thus an ever 473 * increasing value. 474 * 475 * The upstream element can use the @diff and @timestamp values to decide 476 * whether to process more buffers. For positive @diff, all buffers with 477 * timestamp <= @timestamp + @diff will certainly arrive late in the sink 478 * as well. A (negative) @diff value so that @timestamp + @diff would yield a 479 * result smaller than 0 is not allowed. 480 * 481 * The application can use general event probes to intercept the QoS 482 * event and implement custom application specific QoS handling. 483 * 484 * Params: 485 * type = the QoS type 486 * proportion = the proportion of the qos message 487 * diff = The time difference of the last Clock sync 488 * timestamp = The timestamp of the buffer 489 * 490 * Return: a new QOS event. 491 * 492 * Throws: ConstructionException GTK+ fails to create the object. 493 */ 494 public this(GstQOSType type, double proportion, GstClockTimeDiff diff, GstClockTime timestamp) 495 { 496 auto p = gst_event_new_qos(type, proportion, diff, timestamp); 497 498 if(p is null) 499 { 500 throw new ConstructionException("null returned by new_qos"); 501 } 502 503 this(cast(GstEvent*) p); 504 } 505 506 /** 507 * Create a new reconfigure event. The purpose of the reconfigure event is 508 * to travel upstream and make elements renegotiate their caps or reconfigure 509 * their buffer pools. This is useful when changing properties on elements 510 * or changing the topology of the pipeline. 511 * 512 * Return: a new #GstEvent 513 * 514 * Throws: ConstructionException GTK+ fails to create the object. 515 */ 516 public this() 517 { 518 auto p = gst_event_new_reconfigure(); 519 520 if(p is null) 521 { 522 throw new ConstructionException("null returned by new_reconfigure"); 523 } 524 525 this(cast(GstEvent*) p); 526 } 527 528 /** 529 * Allocate a new seek event with the given parameters. 530 * 531 * The seek event configures playback of the pipeline between @start to @stop 532 * at the speed given in @rate, also called a playback segment. 533 * The @start and @stop values are expressed in @format. 534 * 535 * A @rate of 1.0 means normal playback rate, 2.0 means double speed. 536 * Negatives values means backwards playback. A value of 0.0 for the 537 * rate is not allowed and should be accomplished instead by PAUSING the 538 * pipeline. 539 * 540 * A pipeline has a default playback segment configured with a start 541 * position of 0, a stop position of -1 and a rate of 1.0. The currently 542 * configured playback segment can be queried with #GST_QUERY_SEGMENT. 543 * 544 * @start_type and @stop_type specify how to adjust the currently configured 545 * start and stop fields in playback segment. Adjustments can be made relative 546 * or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE 547 * means that the position should not be updated. 548 * 549 * When the rate is positive and @start has been updated, playback will start 550 * from the newly configured start position. 551 * 552 * For negative rates, playback will start from the newly configured stop 553 * position (if any). If the stop position is updated, it must be different from 554 * -1 (#GST_CLOCK_TIME_NONE) for negative rates. 555 * 556 * It is not possible to seek relative to the current playback position, to do 557 * this, PAUSE the pipeline, query the current playback position with 558 * #GST_QUERY_POSITION and update the playback segment current position with a 559 * #GST_SEEK_TYPE_SET to the desired position. 560 * 561 * Params: 562 * rate = The new playback rate 563 * format = The format of the seek values 564 * flags = The optional seek flags 565 * startType = The type and flags for the new start position 566 * start = The value of the new start position 567 * stopType = The type and flags for the new stop position 568 * stop = The value of the new stop position 569 * 570 * Return: a new seek event. 571 * 572 * Throws: ConstructionException GTK+ fails to create the object. 573 */ 574 public this(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, long start, GstSeekType stopType, long stop) 575 { 576 auto p = gst_event_new_seek(rate, format, flags, startType, start, stopType, stop); 577 578 if(p is null) 579 { 580 throw new ConstructionException("null returned by new_seek"); 581 } 582 583 this(cast(GstEvent*) p); 584 } 585 586 /** 587 * Create a new SEGMENT event for @segment. The segment event can only travel 588 * downstream synchronized with the buffer flow and contains timing information 589 * and playback properties for the buffers that will follow. 590 * 591 * The segment event marks the range of buffers to be processed. All 592 * data not within the segment range is not to be processed. This can be 593 * used intelligently by plugins to apply more efficient methods of skipping 594 * unneeded data. The valid range is expressed with the @start and @stop 595 * values. 596 * 597 * The time value of the segment is used in conjunction with the start 598 * value to convert the buffer timestamps into the stream time. This is 599 * usually done in sinks to report the current stream_time. 600 * @time represents the stream_time of a buffer carrying a timestamp of 601 * @start. @time cannot be -1. 602 * 603 * @start cannot be -1, @stop can be -1. If there 604 * is a valid @stop given, it must be greater or equal the @start, including 605 * when the indicated playback @rate is < 0. 606 * 607 * The @applied_rate value provides information about any rate adjustment that 608 * has already been made to the timestamps and content on the buffers of the 609 * stream. (@rate * @applied_rate) should always equal the rate that has been 610 * requested for playback. For example, if an element has an input segment 611 * with intended playback @rate of 2.0 and applied_rate of 1.0, it can adjust 612 * incoming timestamps and buffer content by half and output a segment event 613 * with @rate of 1.0 and @applied_rate of 2.0 614 * 615 * After a segment event, the buffer stream time is calculated with: 616 * 617 * time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) 618 * 619 * Params: 620 * segment = a #GstSegment 621 * 622 * Return: the new SEGMENT event. 623 * 624 * Throws: ConstructionException GTK+ fails to create the object. 625 */ 626 public this(Segment segment) 627 { 628 auto p = gst_event_new_segment((segment is null) ? null : segment.getSegmentStruct()); 629 630 if(p is null) 631 { 632 throw new ConstructionException("null returned by new_segment"); 633 } 634 635 this(cast(GstEvent*) p); 636 } 637 638 /** 639 * Create a new segment-done event. This event is sent by elements that 640 * finish playback of a segment as a result of a segment seek. 641 * 642 * Params: 643 * format = The format of the position being done 644 * position = The position of the segment being done 645 * 646 * Return: a new #GstEvent 647 * 648 * Throws: ConstructionException GTK+ fails to create the object. 649 */ 650 public this(GstFormat format, long position) 651 { 652 auto p = gst_event_new_segment_done(format, position); 653 654 if(p is null) 655 { 656 throw new ConstructionException("null returned by new_segment_done"); 657 } 658 659 this(cast(GstEvent*) p); 660 } 661 662 /** 663 * Create a new sink-message event. The purpose of the sink-message event is 664 * to instruct a sink to post the message contained in the event synchronized 665 * with the stream. 666 * 667 * @name is used to store multiple sticky events on one pad. 668 * 669 * Params: 670 * name = a name for the event 671 * msg = the #GstMessage to be posted 672 * 673 * Return: a new #GstEvent 674 * 675 * Throws: ConstructionException GTK+ fails to create the object. 676 */ 677 public this(string name, Message msg) 678 { 679 auto p = gst_event_new_sink_message(Str.toStringz(name), (msg is null) ? null : msg.getMessageStruct()); 680 681 if(p is null) 682 { 683 throw new ConstructionException("null returned by new_sink_message"); 684 } 685 686 this(cast(GstEvent*) p); 687 } 688 689 /** 690 * Create a new step event. The purpose of the step event is to instruct a sink 691 * to skip @amount (expressed in @format) of media. It can be used to implement 692 * stepping through the video frame by frame or for doing fast trick modes. 693 * 694 * A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate 695 * = 0.0 or first reverse the direction of playback using a seek event to get 696 * the same effect as rate < 0.0. 697 * 698 * The @flush flag will clear any pending data in the pipeline before starting 699 * the step operation. 700 * 701 * The @intermediate flag instructs the pipeline that this step operation is 702 * part of a larger step operation. 703 * 704 * Params: 705 * format = the format of @amount 706 * amount = the amount of data to step 707 * rate = the step rate 708 * flush = flushing steps 709 * intermediate = intermediate steps 710 * 711 * Return: a new #GstEvent 712 * 713 * Throws: ConstructionException GTK+ fails to create the object. 714 */ 715 public this(GstFormat format, ulong amount, double rate, bool flush, bool intermediate) 716 { 717 auto p = gst_event_new_step(format, amount, rate, flush, intermediate); 718 719 if(p is null) 720 { 721 throw new ConstructionException("null returned by new_step"); 722 } 723 724 this(cast(GstEvent*) p); 725 } 726 727 /** 728 * Create a new STREAM_START event. The stream start event can only 729 * travel downstream synchronized with the buffer flow. It is expected 730 * to be the first event that is sent for a new stream. 731 * 732 * Source elements, demuxers and other elements that create new streams 733 * are supposed to send this event as the first event of a new stream. It 734 * should not be sent after a flushing seek or in similar situations 735 * and is used to mark the beginning of a new logical stream. Elements 736 * combining multiple streams must ensure that this event is only forwarded 737 * downstream once and not for every single input stream. 738 * 739 * The @stream_id should be a unique string that consists of the upstream 740 * stream-id, / as separator and a unique stream-id for this specific 741 * stream. A new stream-id should only be created for a stream if the upstream 742 * stream is split into (potentially) multiple new streams, e.g. in a demuxer, 743 * but not for every single element in the pipeline. 744 * gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be 745 * used to create a stream-id. There are no particular semantics for the 746 * stream-id, though it should be deterministic (to support stream matching) 747 * and it might be used to order streams (besides any information conveyed by 748 * stream flags). 749 * 750 * Params: 751 * streamId = Identifier for this stream 752 * 753 * Return: the new STREAM_START event. 754 * 755 * Throws: ConstructionException GTK+ fails to create the object. 756 */ 757 public this(string streamId) 758 { 759 auto p = gst_event_new_stream_start(Str.toStringz(streamId)); 760 761 if(p is null) 762 { 763 throw new ConstructionException("null returned by new_stream_start"); 764 } 765 766 this(cast(GstEvent*) p); 767 } 768 769 /** 770 * Generates a metadata tag event from the given @taglist. 771 * 772 * The scope of the taglist specifies if the taglist applies to the 773 * complete medium or only to this specific stream. As the tag event 774 * is a sticky event, elements should merge tags received from 775 * upstream with a given scope with their own tags with the same 776 * scope and create a new tag event from it. 777 * 778 * Params: 779 * taglist = metadata list. The event will take ownership 780 * of the taglist. 781 * 782 * Return: a new #GstEvent 783 * 784 * Throws: ConstructionException GTK+ fails to create the object. 785 */ 786 public this(TagList taglist) 787 { 788 auto p = gst_event_new_tag((taglist is null) ? null : taglist.getTagListStruct()); 789 790 if(p is null) 791 { 792 throw new ConstructionException("null returned by new_tag"); 793 } 794 795 this(cast(GstEvent*) p); 796 } 797 798 /** 799 * Generate a TOC event from the given @toc. The purpose of the TOC event is to 800 * inform elements that some kind of the TOC was found. 801 * 802 * Params: 803 * toc = #GstToc structure. 804 * updated = whether @toc was updated or not. 805 * 806 * Return: a new #GstEvent. 807 * 808 * Throws: ConstructionException GTK+ fails to create the object. 809 */ 810 public this(Toc toc, bool updated) 811 { 812 auto p = gst_event_new_toc((toc is null) ? null : toc.getTocStruct(), updated); 813 814 if(p is null) 815 { 816 throw new ConstructionException("null returned by new_toc"); 817 } 818 819 this(cast(GstEvent*) p); 820 } 821 822 /** 823 * Parses a segment @event and copies the #GstSegment into the location 824 * given by @segment. 825 * 826 * Params: 827 * segment = a pointer to a #GstSegment 828 */ 829 public void copySegment(Segment segment) 830 { 831 gst_event_copy_segment(gstEvent, (segment is null) ? null : segment.getSegmentStruct()); 832 } 833 834 /** 835 * Retrieve the accumulated running time offset of the event. 836 * 837 * Events passing through #GstPads that have a running time 838 * offset set via gst_pad_set_offset() will get their offset 839 * adjusted according to the pad's offset. 840 * 841 * If the event contains any information that related to the 842 * running time, this information will need to be updated 843 * before usage with this offset. 844 * 845 * Return: The event's running time offset 846 * 847 * MT safe. 848 * 849 * Since: 1.4 850 */ 851 public long getRunningTimeOffset() 852 { 853 return gst_event_get_running_time_offset(gstEvent); 854 } 855 856 /** 857 * Retrieve the sequence number of a event. 858 * 859 * Events have ever-incrementing sequence numbers, which may also be set 860 * explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to 861 * indicate that a event corresponds to some other set of events or messages, 862 * for example an EOS event corresponding to a SEEK event. It is considered good 863 * practice to make this correspondence when possible, though it is not 864 * required. 865 * 866 * Note that events and messages share the same sequence number incrementor; 867 * two events or messages will never have the same sequence number unless 868 * that correspondence was made explicitly. 869 * 870 * Return: The event's sequence number. 871 * 872 * MT safe. 873 */ 874 public uint getSeqnum() 875 { 876 return gst_event_get_seqnum(gstEvent); 877 } 878 879 /** 880 * Access the structure of the event. 881 * 882 * Return: The structure of the event. The structure is still 883 * owned by the event, which means that you should not free it and 884 * that the pointer becomes invalid when you free the event. 885 * 886 * MT safe. 887 */ 888 public Structure getStructure() 889 { 890 auto p = gst_event_get_structure(gstEvent); 891 892 if(p is null) 893 { 894 return null; 895 } 896 897 return ObjectG.getDObject!(Structure)(cast(GstStructure*) p); 898 } 899 900 /** 901 * Checks if @event has the given @name. This function is usually used to 902 * check the name of a custom event. 903 * 904 * Params: 905 * name = name to check 906 * 907 * Return: %TRUE if @name matches the name of the event structure. 908 */ 909 public bool hasName(string name) 910 { 911 return gst_event_has_name(gstEvent, Str.toStringz(name)) != 0; 912 } 913 914 /** 915 * Get the format, minsize, maxsize and async-flag in the buffersize event. 916 * 917 * Params: 918 * format = A pointer to store the format in 919 * minsize = A pointer to store the minsize in 920 * maxsize = A pointer to store the maxsize in 921 * async = A pointer to store the async-flag in 922 */ 923 public void parseBufferSize(out GstFormat format, out long minsize, out long maxsize, out bool async) 924 { 925 int outasync; 926 927 gst_event_parse_buffer_size(gstEvent, &format, &minsize, &maxsize, &outasync); 928 929 async = (outasync == 1); 930 } 931 932 /** 933 * Get the caps from @event. The caps remains valid as long as @event remains 934 * valid. 935 * 936 * Params: 937 * caps = A pointer to the caps 938 */ 939 public void parseCaps(out Caps caps) 940 { 941 GstCaps* outcaps = null; 942 943 gst_event_parse_caps(gstEvent, &outcaps); 944 945 caps = ObjectG.getDObject!(Caps)(outcaps); 946 } 947 948 /** 949 * Parse the FLUSH_STOP event and retrieve the @reset_time member. 950 * 951 * Params: 952 * resetTime = if time should be reset 953 */ 954 public void parseFlushStop(out bool resetTime) 955 { 956 int outresetTime; 957 958 gst_event_parse_flush_stop(gstEvent, &outresetTime); 959 960 resetTime = (outresetTime == 1); 961 } 962 963 /** 964 * Extract timestamp and duration from a new GAP event. 965 * 966 * Params: 967 * timestamp = location where to store the 968 * start time (pts) of the gap, or %NULL 969 * duration = location where to store the duration of 970 * the gap, or %NULL 971 */ 972 public void parseGap(out GstClockTime timestamp, out GstClockTime duration) 973 { 974 gst_event_parse_gap(gstEvent, ×tamp, &duration); 975 } 976 977 /** 978 * 979 * Params: 980 * groupId = address of variable where to store the group id 981 * Return: %TRUE if a group id was set on the event and could be parsed, 982 * %FALSE otherwise. 983 * 984 * Since: 1.2 985 */ 986 public bool parseGroupId(out uint groupId) 987 { 988 return gst_event_parse_group_id(gstEvent, &groupId) != 0; 989 } 990 991 /** 992 * Get the latency in the latency event. 993 * 994 * Params: 995 * latency = A pointer to store the latency in. 996 */ 997 public void parseLatency(out GstClockTime latency) 998 { 999 gst_event_parse_latency(gstEvent, &latency); 1000 } 1001 1002 /** 1003 * Parses an event containing protection system specific information and stores 1004 * the results in @system_id, @data and @origin. The data stored in @system_id, 1005 * @origin and @data are valid until @event is released. 1006 * 1007 * Params: 1008 * systemId = pointer to store the UUID 1009 * string uniquely identifying a content protection system. 1010 * data = pointer to store a #GstBuffer 1011 * holding protection system specific information. 1012 * origin = pointer to store a value that 1013 * indicates where the protection information carried by @event was extracted 1014 * from. 1015 * 1016 * Since: 1.6 1017 */ 1018 public void parseProtection(out string systemId, out Buffer data, string[] origin) 1019 { 1020 char* outsystemId = null; 1021 GstBuffer* outdata = null; 1022 1023 gst_event_parse_protection(gstEvent, &outsystemId, &outdata, Str.toStringzArray(origin)); 1024 1025 systemId = Str.toString(outsystemId); 1026 data = ObjectG.getDObject!(Buffer)(outdata); 1027 } 1028 1029 /** 1030 * Get the type, proportion, diff and timestamp in the qos event. See 1031 * gst_event_new_qos() for more information about the different QoS values. 1032 * 1033 * @timestamp will be adjusted for any pad offsets of pads it was passing through. 1034 * 1035 * Params: 1036 * type = A pointer to store the QoS type in 1037 * proportion = A pointer to store the proportion in 1038 * diff = A pointer to store the diff in 1039 * timestamp = A pointer to store the timestamp in 1040 */ 1041 public void parseQos(out GstQOSType type, out double proportion, out GstClockTimeDiff diff, out GstClockTime timestamp) 1042 { 1043 gst_event_parse_qos(gstEvent, &type, &proportion, &diff, ×tamp); 1044 } 1045 1046 /** 1047 * Parses a seek @event and stores the results in the given result locations. 1048 * 1049 * Params: 1050 * rate = result location for the rate 1051 * format = result location for the stream format 1052 * flags = result location for the #GstSeekFlags 1053 * startType = result location for the #GstSeekType of the start position 1054 * start = result location for the start position expressed in @format 1055 * stopType = result location for the #GstSeekType of the stop position 1056 * stop = result location for the stop position expressed in @format 1057 */ 1058 public void parseSeek(out double rate, out GstFormat format, out GstSeekFlags flags, out GstSeekType startType, out long start, out GstSeekType stopType, out long stop) 1059 { 1060 gst_event_parse_seek(gstEvent, &rate, &format, &flags, &startType, &start, &stopType, &stop); 1061 } 1062 1063 /** 1064 * Parses a segment @event and stores the result in the given @segment location. 1065 * @segment remains valid only until the @event is freed. Don't modify the segment 1066 * and make a copy if you want to modify it or store it for later use. 1067 * 1068 * Params: 1069 * segment = a pointer to a #GstSegment 1070 */ 1071 public void parseSegment(out Segment segment) 1072 { 1073 GstSegment* outsegment = null; 1074 1075 gst_event_parse_segment(gstEvent, &outsegment); 1076 1077 segment = ObjectG.getDObject!(Segment)(outsegment); 1078 } 1079 1080 /** 1081 * Extracts the position and format from the segment done message. 1082 * 1083 * Params: 1084 * format = Result location for the format, or %NULL 1085 * position = Result location for the position, or %NULL 1086 */ 1087 public void parseSegmentDone(out GstFormat format, out long position) 1088 { 1089 gst_event_parse_segment_done(gstEvent, &format, &position); 1090 } 1091 1092 /** 1093 * Parse the sink-message event. Unref @msg after usage. 1094 * 1095 * Params: 1096 * msg = a pointer to store the #GstMessage in. 1097 */ 1098 public void parseSinkMessage(out Message msg) 1099 { 1100 GstMessage* outmsg = null; 1101 1102 gst_event_parse_sink_message(gstEvent, &outmsg); 1103 1104 msg = ObjectG.getDObject!(Message)(outmsg); 1105 } 1106 1107 /** 1108 * Parse the step event. 1109 * 1110 * Params: 1111 * format = a pointer to store the format in 1112 * amount = a pointer to store the amount in 1113 * rate = a pointer to store the rate in 1114 * flush = a pointer to store the flush boolean in 1115 * intermediate = a pointer to store the intermediate 1116 * boolean in 1117 */ 1118 public void parseStep(out GstFormat format, out ulong amount, out double rate, out bool flush, out bool intermediate) 1119 { 1120 int outflush; 1121 int outintermediate; 1122 1123 gst_event_parse_step(gstEvent, &format, &amount, &rate, &outflush, &outintermediate); 1124 1125 flush = (outflush == 1); 1126 intermediate = (outintermediate == 1); 1127 } 1128 1129 /** */ 1130 public void parseStreamFlags(out GstStreamFlags flags) 1131 { 1132 gst_event_parse_stream_flags(gstEvent, &flags); 1133 } 1134 1135 /** 1136 * Parse a stream-id @event and store the result in the given @stream_id 1137 * location. The string stored in @stream_id must not be modified and will 1138 * remain valid only until @event gets freed. Make a copy if you want to 1139 * modify it or store it for later use. 1140 * 1141 * Params: 1142 * streamId = pointer to store the stream-id 1143 */ 1144 public void parseStreamStart(out string streamId) 1145 { 1146 char* outstreamId = null; 1147 1148 gst_event_parse_stream_start(gstEvent, &outstreamId); 1149 1150 streamId = Str.toString(outstreamId); 1151 } 1152 1153 /** 1154 * Parses a tag @event and stores the results in the given @taglist location. 1155 * No reference to the taglist will be returned, it remains valid only until 1156 * the @event is freed. Don't modify or free the taglist, make a copy if you 1157 * want to modify it or store it for later use. 1158 * 1159 * Params: 1160 * taglist = pointer to metadata list 1161 */ 1162 public void parseTag(out TagList taglist) 1163 { 1164 GstTagList* outtaglist = null; 1165 1166 gst_event_parse_tag(gstEvent, &outtaglist); 1167 1168 taglist = ObjectG.getDObject!(TagList)(outtaglist); 1169 } 1170 1171 /** 1172 * Parse a TOC @event and store the results in the given @toc and @updated locations. 1173 * 1174 * Params: 1175 * toc = pointer to #GstToc structure. 1176 * updated = pointer to store TOC updated flag. 1177 */ 1178 public void parseToc(out Toc toc, out bool updated) 1179 { 1180 GstToc* outtoc = null; 1181 int outupdated; 1182 1183 gst_event_parse_toc(gstEvent, &outtoc, &outupdated); 1184 1185 toc = ObjectG.getDObject!(Toc)(outtoc); 1186 updated = (outupdated == 1); 1187 } 1188 1189 /** 1190 * Parse a TOC select @event and store the results in the given @uid location. 1191 * 1192 * Params: 1193 * uid = storage for the selection UID. 1194 */ 1195 public void parseTocSelect(out string uid) 1196 { 1197 char* outuid = null; 1198 1199 gst_event_parse_toc_select(gstEvent, &outuid); 1200 1201 uid = Str.toString(outuid); 1202 } 1203 1204 /** 1205 * All streams that have the same group id are supposed to be played 1206 * together, i.e. all streams inside a container file should have the 1207 * same group id but different stream ids. The group id should change 1208 * each time the stream is started, resulting in different group ids 1209 * each time a file is played for example. 1210 * 1211 * Use gst_util_group_id_next() to get a new group id. 1212 * 1213 * Params: 1214 * groupId = the group id to set 1215 * 1216 * Since: 1.2 1217 */ 1218 public void setGroupId(uint groupId) 1219 { 1220 gst_event_set_group_id(gstEvent, groupId); 1221 } 1222 1223 /** 1224 * Set the running time offset of a event. See 1225 * gst_event_get_running_time_offset() for more information. 1226 * 1227 * MT safe. 1228 * 1229 * Params: 1230 * offset = A the new running time offset 1231 * 1232 * Since: 1.4 1233 */ 1234 public void setRunningTimeOffset(long offset) 1235 { 1236 gst_event_set_running_time_offset(gstEvent, offset); 1237 } 1238 1239 /** 1240 * Set the sequence number of a event. 1241 * 1242 * This function might be called by the creator of a event to indicate that the 1243 * event relates to other events or messages. See gst_event_get_seqnum() for 1244 * more information. 1245 * 1246 * MT safe. 1247 * 1248 * Params: 1249 * seqnum = A sequence number. 1250 */ 1251 public void setSeqnum(uint seqnum) 1252 { 1253 gst_event_set_seqnum(gstEvent, seqnum); 1254 } 1255 1256 /** */ 1257 public void setStreamFlags(GstStreamFlags flags) 1258 { 1259 gst_event_set_stream_flags(gstEvent, flags); 1260 } 1261 1262 /** 1263 * Get a writable version of the structure. 1264 * 1265 * Return: The structure of the event. The structure 1266 * is still owned by the event, which means that you should not free 1267 * it and that the pointer becomes invalid when you free the event. 1268 * This function checks if @event is writable and will never return 1269 * %NULL. 1270 * 1271 * MT safe. 1272 */ 1273 public Structure writableStructure() 1274 { 1275 auto p = gst_event_writable_structure(gstEvent); 1276 1277 if(p is null) 1278 { 1279 return null; 1280 } 1281 1282 return ObjectG.getDObject!(Structure)(cast(GstStructure*) p); 1283 } 1284 1285 /** 1286 * Gets the #GstEventTypeFlags associated with @type. 1287 * 1288 * Params: 1289 * type = a #GstEventType 1290 * 1291 * Return: a #GstEventTypeFlags. 1292 */ 1293 public static GstEventTypeFlags typeGetFlags(GstEventType type) 1294 { 1295 return gst_event_type_get_flags(type); 1296 } 1297 1298 /** 1299 * Get a printable name for the given event type. Do not modify or free. 1300 * 1301 * Params: 1302 * type = the event type 1303 * 1304 * Return: a reference to the static name of the event. 1305 */ 1306 public static string typeGetName(GstEventType type) 1307 { 1308 return Str.toString(gst_event_type_get_name(type)); 1309 } 1310 1311 /** 1312 * Get the unique quark for the given event type. 1313 * 1314 * Params: 1315 * type = the event type 1316 * 1317 * Return: the quark associated with the event type 1318 */ 1319 public static GQuark typeToQuark(GstEventType type) 1320 { 1321 return gst_event_type_to_quark(type); 1322 } 1323 }