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.ObjectGst; 26 27 private import glib.ErrorG; 28 private import glib.ListG; 29 private import glib.Str; 30 private import gobject.ObjectG; 31 private import gobject.ParamSpec; 32 private import gobject.Signals; 33 private import gobject.Value; 34 private import gstreamer.ControlBinding; 35 private import gstreamerc.gstreamer; 36 public import gstreamerc.gstreamertypes; 37 public import gtkc.gdktypes; 38 39 40 /** 41 * #GstObject provides a root for the object hierarchy tree filed in by the 42 * GStreamer library. It is currently a thin wrapper on top of 43 * #GInitiallyUnowned. It is an abstract class that is not very usable on its own. 44 * 45 * #GstObject gives us basic refcounting, parenting functionality and locking. 46 * Most of the functions are just extended for special GStreamer needs and can be 47 * found under the same name in the base class of #GstObject which is #GObject 48 * (e.g. g_object_ref() becomes gst_object_ref()). 49 * 50 * Since #GstObject derives from #GInitiallyUnowned, it also inherits the 51 * floating reference. Be aware that functions such as gst_bin_add() and 52 * gst_element_add_pad() take ownership of the floating reference. 53 * 54 * In contrast to #GObject instances, #GstObject adds a name property. The functions 55 * gst_object_set_name() and gst_object_get_name() are used to set/get the name 56 * of the object. 57 * 58 * <refsect2> 59 * <title>controlled properties</title> 60 * <para> 61 * Controlled properties offers a lightweight way to adjust gobject properties 62 * over stream-time. It works by using time-stamped value pairs that are queued 63 * for element-properties. At run-time the elements continuously pull value 64 * changes for the current stream-time. 65 * 66 * What needs to be changed in a #GstElement? 67 * Very little - it is just two steps to make a plugin controllable! 68 * <orderedlist> 69 * <listitem><para> 70 * mark gobject-properties paramspecs that make sense to be controlled, 71 * by GST_PARAM_CONTROLLABLE. 72 * </para></listitem> 73 * <listitem><para> 74 * when processing data (get, chain, loop function) at the beginning call 75 * gst_object_sync_values(element,timestamp). 76 * This will make the controller update all GObject properties that are 77 * under its control with the current values based on the timestamp. 78 * </para></listitem> 79 * </orderedlist> 80 * 81 * What needs to be done in applications? 82 * Again it's not a lot to change. 83 * <orderedlist> 84 * <listitem><para> 85 * create a #GstControlSource. 86 * csource = gst_interpolation_control_source_new (); 87 * g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); 88 * </para></listitem> 89 * <listitem><para> 90 * Attach the #GstControlSource on the controller to a property. 91 * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); 92 * </para></listitem> 93 * <listitem><para> 94 * Set the control values 95 * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); 96 * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); 97 * </para></listitem> 98 * <listitem><para> 99 * start your pipeline 100 * </para></listitem> 101 * </orderedlist> 102 * </para> 103 * </refsect2> 104 */ 105 public class ObjectGst : ObjectG 106 { 107 /** the main Gtk struct */ 108 protected GstObject* gstObject; 109 110 /** Get the main Gtk struct */ 111 public GstObject* getObjectGstStruct() 112 { 113 return gstObject; 114 } 115 116 /** the main Gtk struct as a void* */ 117 protected override void* getStruct() 118 { 119 return cast(void*)gstObject; 120 } 121 122 protected override void setStruct(GObject* obj) 123 { 124 gstObject = cast(GstObject*)obj; 125 super.setStruct(obj); 126 } 127 128 /** 129 * Sets our main struct and passes it to the parent class. 130 */ 131 public this (GstObject* gstObject, bool ownedRef = false) 132 { 133 this.gstObject = gstObject; 134 super(cast(GObject*)gstObject, ownedRef); 135 } 136 137 138 /** */ 139 public static GType getType() 140 { 141 return gst_object_get_type(); 142 } 143 144 /** 145 * Checks to see if there is any object named @name in @list. This function 146 * does not do any locking of any kind. You might want to protect the 147 * provided list with the lock of the owner of the list. This function 148 * will lock each #GstObject in the list to compare the name, so be 149 * careful when passing a list with a locked object. 150 * 151 * Params: 152 * list = a list of #GstObject to 153 * check through 154 * name = the name to search for 155 * 156 * Return: %TRUE if a #GstObject named @name does not appear in @list, 157 * %FALSE if it does. 158 * 159 * MT safe. Grabs and releases the LOCK of each object in the list. 160 */ 161 public static bool checkUniqueness(ListG list, string name) 162 { 163 return gst_object_check_uniqueness((list is null) ? null : list.getListGStruct(), Str.toStringz(name)) != 0; 164 } 165 166 /** 167 * A default deep_notify signal callback for an object. The user data 168 * should contain a pointer to an array of strings that should be excluded 169 * from the notify. The default handler will print the new value of the property 170 * using g_print. 171 * 172 * MT safe. This function grabs and releases @object's LOCK for getting its 173 * path string. 174 * 175 * Params: 176 * object = the #GObject that signalled the notify. 177 * orig = a #GstObject that initiated the notify. 178 * pspec = a #GParamSpec of the property. 179 * excludedProps = a set of user-specified properties to exclude or %NULL to show 180 * all changes. 181 */ 182 public static void defaultDeepNotify(ObjectG object, ObjectGst orig, ParamSpec pspec, string[] excludedProps) 183 { 184 gst_object_default_deep_notify((object is null) ? null : object.getObjectGStruct(), (orig is null) ? null : orig.getObjectGstStruct(), (pspec is null) ? null : pspec.getParamSpecStruct(), Str.toStringzArray(excludedProps)); 185 } 186 187 /** 188 * Increase the reference count of @object, and possibly remove the floating 189 * reference, if @object has a floating reference. 190 * 191 * In other words, if the object is floating, then this call "assumes ownership" 192 * of the floating reference, converting it to a normal reference by clearing 193 * the floating flag while leaving the reference count unchanged. If the object 194 * is not floating, then this call adds a new normal reference increasing the 195 * reference count by one. 196 * 197 * Params: 198 * object = a #GstObject to sink 199 */ 200 public static void* refSink(void* object) 201 { 202 return gst_object_ref_sink(object); 203 } 204 205 /** 206 * Atomically modifies a pointer to point to a new object. 207 * The reference count of @oldobj is decreased and the reference count of 208 * @newobj is increased. 209 * 210 * Either @newobj and the value pointed to by @oldobj may be %NULL. 211 * 212 * Params: 213 * oldobj = pointer to a place of 214 * a #GstObject to replace 215 * newobj = a new #GstObject 216 * 217 * Return: %TRUE if @newobj was different from @oldobj 218 */ 219 public static bool replace(ref ObjectGst oldobj, ObjectGst newobj) 220 { 221 GstObject* outoldobj = oldobj.getObjectGstStruct(); 222 223 auto p = gst_object_replace(&outoldobj, (newobj is null) ? null : newobj.getObjectGstStruct()) != 0; 224 225 oldobj = ObjectG.getDObject!(ObjectGst)(outoldobj); 226 227 return p; 228 } 229 230 /** 231 * Attach the #GstControlBinding to the object. If there already was a 232 * #GstControlBinding for this property it will be replaced. 233 * 234 * The @object will take ownership of the @binding. 235 * 236 * Params: 237 * binding = the #GstControlBinding that should be used 238 * 239 * Return: %FALSE if the given @binding has not been setup for this object or 240 * has been setup for a non suitable property, %TRUE otherwise. 241 */ 242 public bool addControlBinding(ControlBinding binding) 243 { 244 return gst_object_add_control_binding(gstObject, (binding is null) ? null : binding.getControlBindingStruct()) != 0; 245 } 246 247 /** 248 * A default error function that uses g_printerr() to display the error message 249 * and the optional debug sting.. 250 * 251 * The default handler will simply print the error string using g_print. 252 * 253 * Params: 254 * error = the GError. 255 * dbg = an additional debug information string, or %NULL 256 */ 257 public void defaultError(ErrorG error, string dbg) 258 { 259 gst_object_default_error(gstObject, (error is null) ? null : error.getErrorGStruct(), Str.toStringz(dbg)); 260 } 261 262 /** 263 * Gets the corresponding #GstControlBinding for the property. This should be 264 * unreferenced again after use. 265 * 266 * Params: 267 * propertyName = name of the property 268 * 269 * Return: the #GstControlBinding for 270 * @property_name or %NULL if the property is not controlled. 271 */ 272 public ControlBinding getControlBinding(string propertyName) 273 { 274 auto p = gst_object_get_control_binding(gstObject, Str.toStringz(propertyName)); 275 276 if(p is null) 277 { 278 return null; 279 } 280 281 return ObjectG.getDObject!(ControlBinding)(cast(GstControlBinding*) p, true); 282 } 283 284 /** 285 * Obtain the control-rate for this @object. Audio processing #GstElement 286 * objects will use this rate to sub-divide their processing loop and call 287 * gst_object_sync_values() inbetween. The length of the processing segment 288 * should be up to @control-rate nanoseconds. 289 * 290 * If the @object is not under property control, this will return 291 * %GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing. 292 * 293 * The control-rate is not expected to change if the element is in 294 * %GST_STATE_PAUSED or %GST_STATE_PLAYING. 295 * 296 * Return: the control rate in nanoseconds 297 */ 298 public GstClockTime getControlRate() 299 { 300 return gst_object_get_control_rate(gstObject); 301 } 302 303 /** 304 * Gets a number of #GValues for the given controlled property starting at the 305 * requested time. The array @values need to hold enough space for @n_values of 306 * #GValue. 307 * 308 * This function is useful if one wants to e.g. draw a graph of the control 309 * curve or apply a control curve sample by sample. 310 * 311 * Params: 312 * propertyName = the name of the property to get 313 * timestamp = the time that should be processed 314 * interval = the time spacing between subsequent values 315 * nValues = the number of values 316 * values = array to put control-values in 317 * 318 * Return: %TRUE if the given array could be filled, %FALSE otherwise 319 */ 320 public bool getGValueArray(string propertyName, GstClockTime timestamp, GstClockTime interval, uint nValues, Value values) 321 { 322 return gst_object_get_g_value_array(gstObject, Str.toStringz(propertyName), timestamp, interval, nValues, (values is null) ? null : values.getValueStruct()) != 0; 323 } 324 325 /** 326 * Returns a copy of the name of @object. 327 * Caller should g_free() the return value after usage. 328 * For a nameless object, this returns %NULL, which you can safely g_free() 329 * as well. 330 * 331 * Free-function: g_free 332 * 333 * Return: the name of @object. g_free() 334 * after usage. 335 * 336 * MT safe. This function grabs and releases @object's LOCK. 337 */ 338 public string getName() 339 { 340 auto retStr = gst_object_get_name(gstObject); 341 342 scope(exit) Str.freeString(retStr); 343 return Str.toString(retStr); 344 } 345 346 /** 347 * Returns the parent of @object. This function increases the refcount 348 * of the parent object so you should gst_object_unref() it after usage. 349 * 350 * Return: parent of @object, this can be 351 * %NULL if @object has no parent. unref after usage. 352 * 353 * MT safe. Grabs and releases @object's LOCK. 354 */ 355 public ObjectGst getParent() 356 { 357 auto p = gst_object_get_parent(gstObject); 358 359 if(p is null) 360 { 361 return null; 362 } 363 364 return ObjectG.getDObject!(ObjectGst)(cast(GstObject*) p, true); 365 } 366 367 /** 368 * Generates a string describing the path of @object in 369 * the object hierarchy. Only useful (or used) for debugging. 370 * 371 * Free-function: g_free 372 * 373 * Return: a string describing the path of @object. You must 374 * g_free() the string after usage. 375 * 376 * MT safe. Grabs and releases the #GstObject's LOCK for all objects 377 * in the hierarchy. 378 */ 379 public string getPathString() 380 { 381 auto retStr = gst_object_get_path_string(gstObject); 382 383 scope(exit) Str.freeString(retStr); 384 return Str.toString(retStr); 385 } 386 387 /** 388 * Gets the value for the given controlled property at the requested time. 389 * 390 * Params: 391 * propertyName = the name of the property to get 392 * timestamp = the time the control-change should be read from 393 * 394 * Return: the GValue of the property at the given time, 395 * or %NULL if the property isn't controlled. 396 */ 397 public Value getValue(string propertyName, GstClockTime timestamp) 398 { 399 auto p = gst_object_get_value(gstObject, Str.toStringz(propertyName), timestamp); 400 401 if(p is null) 402 { 403 return null; 404 } 405 406 return ObjectG.getDObject!(Value)(cast(GValue*) p, true); 407 } 408 409 /** 410 * Gets a number of values for the given controlled property starting at the 411 * requested time. The array @values need to hold enough space for @n_values of 412 * the same type as the objects property's type. 413 * 414 * This function is useful if one wants to e.g. draw a graph of the control 415 * curve or apply a control curve sample by sample. 416 * 417 * The values are unboxed and ready to be used. The similar function 418 * gst_object_get_g_value_array() returns the array as #GValues and is 419 * better suites for bindings. 420 * 421 * Params: 422 * propertyName = the name of the property to get 423 * timestamp = the time that should be processed 424 * interval = the time spacing between subsequent values 425 * nValues = the number of values 426 * values = array to put control-values in 427 * 428 * Return: %TRUE if the given array could be filled, %FALSE otherwise 429 */ 430 public bool getValueArray(string propertyName, GstClockTime timestamp, GstClockTime interval, uint nValues, void* values) 431 { 432 return gst_object_get_value_array(gstObject, Str.toStringz(propertyName), timestamp, interval, nValues, values) != 0; 433 } 434 435 /** 436 * Check if the @object has an active controlled properties. 437 * 438 * Return: %TRUE if the object has active controlled properties 439 */ 440 public bool hasActiveControlBindings() 441 { 442 return gst_object_has_active_control_bindings(gstObject) != 0; 443 } 444 445 /** 446 * Check if @object has an ancestor @ancestor somewhere up in 447 * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. 448 * 449 * Deprecated: Use gst_object_has_as_ancestor() instead. 450 * 451 * MT safe. Grabs and releases @object's locks. 452 * 453 * Params: 454 * ancestor = a #GstObject to check as ancestor 455 * 456 * Return: %TRUE if @ancestor is an ancestor of @object. 457 */ 458 public bool hasAncestor(ObjectGst ancestor) 459 { 460 return gst_object_has_ancestor(gstObject, (ancestor is null) ? null : ancestor.getObjectGstStruct()) != 0; 461 } 462 463 /** 464 * Check if @object has an ancestor @ancestor somewhere up in 465 * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. 466 * 467 * Params: 468 * ancestor = a #GstObject to check as ancestor 469 * 470 * Return: %TRUE if @ancestor is an ancestor of @object. 471 * 472 * MT safe. Grabs and releases @object's locks. 473 */ 474 public bool hasAsAncestor(ObjectGst ancestor) 475 { 476 return gst_object_has_as_ancestor(gstObject, (ancestor is null) ? null : ancestor.getObjectGstStruct()) != 0; 477 } 478 479 /** 480 * Check if @parent is the parent of @object. 481 * E.g. a #GstElement can check if it owns a given #GstPad. 482 * 483 * Params: 484 * parent = a #GstObject to check as parent 485 * 486 * Return: %FALSE if either @object or @parent is %NULL. %TRUE if @parent is 487 * the parent of @object. Otherwise %FALSE. 488 * 489 * MT safe. Grabs and releases @object's locks. 490 * 491 * Since: 1.6 492 */ 493 public bool hasAsParent(ObjectGst parent) 494 { 495 return gst_object_has_as_parent(gstObject, (parent is null) ? null : parent.getObjectGstStruct()) != 0; 496 } 497 498 /** 499 * Increments the reference count on @object. This function 500 * does not take the lock on @object because it relies on 501 * atomic refcounting. 502 * 503 * This object returns the input parameter to ease writing 504 * constructs like : 505 * result = gst_object_ref (object->parent); 506 * 507 * Return: A pointer to @object 508 */ 509 public override ObjectGst doref() 510 { 511 auto p = gst_object_ref(gstObject); 512 513 if(p is null) 514 { 515 return null; 516 } 517 518 return ObjectG.getDObject!(ObjectGst)(cast(GstObject*) p, true); 519 } 520 521 /** 522 * Removes the corresponding #GstControlBinding. If it was the 523 * last ref of the binding, it will be disposed. 524 * 525 * Params: 526 * binding = the binding 527 * 528 * Return: %TRUE if the binding could be removed. 529 */ 530 public bool removeControlBinding(ControlBinding binding) 531 { 532 return gst_object_remove_control_binding(gstObject, (binding is null) ? null : binding.getControlBindingStruct()) != 0; 533 } 534 535 /** 536 * This function is used to disable the control bindings on a property for 537 * some time, i.e. gst_object_sync_values() will do nothing for the 538 * property. 539 * 540 * Params: 541 * propertyName = property to disable 542 * disabled = boolean that specifies whether to disable the controller 543 * or not. 544 */ 545 public void setControlBindingDisabled(string propertyName, bool disabled) 546 { 547 gst_object_set_control_binding_disabled(gstObject, Str.toStringz(propertyName), disabled); 548 } 549 550 /** 551 * This function is used to disable all controlled properties of the @object for 552 * some time, i.e. gst_object_sync_values() will do nothing. 553 * 554 * Params: 555 * disabled = boolean that specifies whether to disable the controller 556 * or not. 557 */ 558 public void setControlBindingsDisabled(bool disabled) 559 { 560 gst_object_set_control_bindings_disabled(gstObject, disabled); 561 } 562 563 /** 564 * Change the control-rate for this @object. Audio processing #GstElement 565 * objects will use this rate to sub-divide their processing loop and call 566 * gst_object_sync_values() inbetween. The length of the processing segment 567 * should be up to @control-rate nanoseconds. 568 * 569 * The control-rate should not change if the element is in %GST_STATE_PAUSED or 570 * %GST_STATE_PLAYING. 571 * 572 * Params: 573 * controlRate = the new control-rate in nanoseconds. 574 */ 575 public void setControlRate(GstClockTime controlRate) 576 { 577 gst_object_set_control_rate(gstObject, controlRate); 578 } 579 580 /** 581 * Sets the name of @object, or gives @object a guaranteed unique 582 * name (if @name is %NULL). 583 * This function makes a copy of the provided name, so the caller 584 * retains ownership of the name it sent. 585 * 586 * Params: 587 * name = new name of object 588 * 589 * Return: %TRUE if the name could be set. Since Objects that have 590 * a parent cannot be renamed, this function returns %FALSE in those 591 * cases. 592 * 593 * MT safe. This function grabs and releases @object's LOCK. 594 */ 595 public bool setName(string name) 596 { 597 return gst_object_set_name(gstObject, Str.toStringz(name)) != 0; 598 } 599 600 /** 601 * Sets the parent of @object to @parent. The object's reference count will 602 * be incremented, and any floating reference will be removed (see gst_object_ref_sink()). 603 * 604 * Params: 605 * parent = new parent of object 606 * 607 * Return: %TRUE if @parent could be set or %FALSE when @object 608 * already had a parent or @object and @parent are the same. 609 * 610 * MT safe. Grabs and releases @object's LOCK. 611 */ 612 public bool setParent(ObjectGst parent) 613 { 614 return gst_object_set_parent(gstObject, (parent is null) ? null : parent.getObjectGstStruct()) != 0; 615 } 616 617 /** 618 * Returns a suggestion for timestamps where buffers should be split 619 * to get best controller results. 620 * 621 * Return: Returns the suggested timestamp or %GST_CLOCK_TIME_NONE 622 * if no control-rate was set. 623 */ 624 public GstClockTime suggestNextSync() 625 { 626 return gst_object_suggest_next_sync(gstObject); 627 } 628 629 /** 630 * Sets the properties of the object, according to the #GstControlSources that 631 * (maybe) handle them and for the given timestamp. 632 * 633 * If this function fails, it is most likely the application developers fault. 634 * Most probably the control sources are not setup correctly. 635 * 636 * Params: 637 * timestamp = the time that should be processed 638 * 639 * Return: %TRUE if the controller values could be applied to the object 640 * properties, %FALSE otherwise 641 */ 642 public bool syncValues(GstClockTime timestamp) 643 { 644 return gst_object_sync_values(gstObject, timestamp) != 0; 645 } 646 647 /** 648 * Clear the parent of @object, removing the associated reference. 649 * This function decreases the refcount of @object. 650 * 651 * MT safe. Grabs and releases @object's lock. 652 */ 653 public void unparent() 654 { 655 gst_object_unparent(gstObject); 656 } 657 658 /** 659 * Decrements the reference count on @object. If reference count hits 660 * zero, destroy @object. This function does not take the lock 661 * on @object as it relies on atomic refcounting. 662 * 663 * The unref method should never be called with the LOCK held since 664 * this might deadlock the dispose function. 665 */ 666 public override void unref() 667 { 668 gst_object_unref(gstObject); 669 } 670 671 int[string] connectedSignals; 672 673 void delegate(ObjectGst, ParamSpec, ObjectGst)[] onDeepNotifyListeners; 674 /** 675 * The deep notify signal is used to be notified of property changes. It is 676 * typically attached to the toplevel bin to receive notifications from all 677 * the elements contained in that bin. 678 * 679 * Params: 680 * propObject = the object that originated the signal 681 * prop = the property that changed 682 */ 683 void addOnDeepNotify(void delegate(ObjectGst, ParamSpec, ObjectGst) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 684 { 685 if ( "deep-notify" !in connectedSignals ) 686 { 687 Signals.connectData( 688 this, 689 "deep-notify", 690 cast(GCallback)&callBackDeepNotify, 691 cast(void*)this, 692 null, 693 connectFlags); 694 connectedSignals["deep-notify"] = 1; 695 } 696 onDeepNotifyListeners ~= dlg; 697 } 698 extern(C) static void callBackDeepNotify(GstObject* objectgstStruct, GstObject* propObject, GParamSpec* prop, ObjectGst _objectgst) 699 { 700 foreach ( void delegate(ObjectGst, ParamSpec, ObjectGst) dlg; _objectgst.onDeepNotifyListeners ) 701 { 702 dlg(ObjectG.getDObject!(ObjectGst)(propObject), ObjectG.getDObject!(ParamSpec)(prop), _objectgst); 703 } 704 } 705 }