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