Class GstObject

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.freedesktop.gstreamer.gst.GstObject
All Implemented Interfaces:
Proxy
Direct Known Subclasses:
Allocator, AudioRingBuffer, BufferPool, Bus, Clock, CollectPads, ControlBinding, ControlSource, Device, DeviceMonitor, DeviceProvider, Element, GstObject.Object$Impl, Pad, PadTemplate, Plugin, PluginFeature, Registry, Stream, StreamCollection, Task, TaskPool, Tracer, TracerRecord
@Generated("org.javagi.JavaGI") public abstract class GstObject extends InitiallyUnowned

GstObject provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of GInitiallyUnowned. It is an abstract class that is not very usable on its own.

GstObject gives us basic refcounting, parenting functionality and locking. Most of the functions are just extended for special GStreamer needs and can be found under the same name in the base class of GstObject which is GObject (e.g. g_object_ref() becomes gst_object_ref()).

Since GstObject derives from GInitiallyUnowned, it also inherits the floating reference. Be aware that functions such as gst_bin_add() and gst_element_add_pad() take ownership of the floating reference.

In contrast to GObject instances, GstObject adds a name property. The functions gst_object_set_name() and gst_object_get_name() are used to set/get the name of the object.

controlled properties

Controlled properties offers a lightweight way to adjust gobject properties over stream-time. It works by using time-stamped value pairs that are queued for element-properties. At run-time the elements continuously pull value changes for the current stream-time.

What needs to be changed in a GstElement? Very little - it is just two steps to make a plugin controllable!

  • mark gobject-properties paramspecs that make sense to be controlled, by GST_PARAM_CONTROLLABLE.

  • when processing data (get, chain, loop function) at the beginning call gst_object_sync_values(element,timestamp). This will make the controller update all GObject properties that are under its control with the current values based on the timestamp.

What needs to be done in applications? Again it's not a lot to change.

  • create a GstControlSource. csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);

  • Attach the GstControlSource on the controller to a property. gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));

  • Set the control values gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);

  • start your pipeline

  • Constructor Details

    • GstObject

      public GstObject(MemorySegment address)
      Create a GstObject instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • GstObject

      public GstObject()
      Create a new GstObject.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the GstObject class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected GstObject asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class InitiallyUnowned
      Returns:
      the instance as if it were its parent type

    • checkUniqueness

      public static boolean checkUniqueness(List<GstObject> list, String name)
      Checks to see if there is any object named name in list. This function does not do any locking of any kind. You might want to protect the provided list with the lock of the owner of the list. This function will lock each GstObject in the list to compare the name, so be careful when passing a list with a locked object.
      Parameters:
      list - a list of GstObject to check through
      name - the name to search for
      Returns:

      true if a GstObject named name does not appear in list, false if it does.

      MT safe. Grabs and releases the LOCK of each object in the list.

    • defaultDeepNotify

      public static void defaultDeepNotify(GObject object, GstObject orig, ParamSpec pspec, @Nullable String @Nullable [] excludedProps)

      A default deep_notify signal callback for an object. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print.

      MT safe. This function grabs and releases object's LOCK for getting its path string.

      Parameters:
      object - the GObject that signalled the notify.
      orig - a GstObject that initiated the notify.
      pspec - a GParamSpec of the property.
      excludedProps - a set of user-specified properties to exclude or null to show all changes.

    • refSink

      public static @Nullable MemorySegment refSink(@Nullable MemorySegment object)

      Increase the reference count of object, and possibly remove the floating reference, if object has a floating reference.

      In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

      For more background on "floating references" please see the GObject documentation.

      Parameters:
      object - a GstObject to sink

    • replace

      public static boolean replace(@Nullable Out<GstObject> oldobj, @Nullable GstObject newobj)

      Atomically modifies a pointer to point to a new object. The reference count of oldobj is decreased and the reference count of newobj is increased.

      Either newobj and the value pointed to by oldobj may be null.

      Parameters:
      oldobj - pointer to a place of a GstObject to replace
      newobj - a new GstObject
      Returns:
      true if newobj was different from oldobj

    • addControlBinding

      public boolean addControlBinding(ControlBinding binding)

      Attach the GstControlBinding to the object. If there already was a GstControlBinding for this property it will be replaced.

      The object's reference count will be incremented, and any floating reference will be removed (see gst_object_ref_sink())

      Parameters:
      binding - the GstControlBinding that should be used
      Returns:
      false if the given binding has not been setup for this object or has been setup for a non suitable property, true otherwise.

    • defaultError

      public void defaultError(GError error, @Nullable String debug)

      A default error function that uses g_printerr() to display the error message and the optional debug string..

      The default handler will simply print the error string using g_print.

      Parameters:
      error - the GError.
      debug - an additional debug information string, or null

    • getControlBinding

      public @Nullable ControlBinding getControlBinding(String propertyName)
      Gets the corresponding GstControlBinding for the property. This should be unreferenced again after use.
      Parameters:
      propertyName - name of the property
      Returns:
      the GstControlBinding for propertyName or null if the property is not controlled.

    • getControlRate

      public ClockTime getControlRate()

      Obtain the control-rate for this object. Audio processing GstElement objects will use this rate to sub-divide their processing loop and call gst_object_sync_values() in between. The length of the processing segment should be up to controlRate nanoseconds.

      If the this Object is not under property control, this will return GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.

      The control-rate is not expected to change if the element is in State.PAUSED or State.PLAYING.

      Returns:
      the control rate in nanoseconds

    • getGValueArray

      public boolean getGValueArray(String propertyName, ClockTime timestamp, ClockTime interval, @Nullable Value @Nullable [] values)

      Gets a number of GValues for the given controlled property starting at the requested time. The array values need to hold enough space for nValues of GValue.

      This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample.

      Parameters:
      propertyName - the name of the property to get
      timestamp - the time that should be processed
      interval - the time spacing between subsequent values
      values - array to put control-values in
      Returns:
      true if the given array could be filled, false otherwise

    • getName

      public @Nullable String getName()

      Returns a copy of the name of object. Caller should g_free() the return value after usage. For a nameless object, this returns null, which you can safely g_free() as well.

      Free-function: g_free

      Returns:

      the name of object. g_free() after usage.

      MT safe. This function grabs and releases object's LOCK.

    • getParent

      public @Nullable GstObject getParent()
      Returns the parent of object. This function increases the refcount of the parent object so you should gst_object_unref() it after usage.
      Returns:

      parent of object, this can be null if this Object has no parent. unref after usage.

      MT safe. Grabs and releases object's LOCK.

    • getPathString

      public String getPathString()

      Generates a string describing the path of this Object in the object hierarchy. Only useful (or used) for debugging.

      Free-function: g_free

      Returns:

      a string describing the path of object. You must g_free() the string after usage.

      MT safe. Grabs and releases the GstObject's LOCK for all objects in the hierarchy.

    • getValue

      public @Nullable Value getValue(String propertyName, ClockTime timestamp)
      Gets the value for the given controlled property at the requested time.
      Parameters:
      propertyName - the name of the property to get
      timestamp - the time the control-change should be read from
      Returns:
      the GValue of the property at the given time, or null if the property isn't controlled.

    • getValueArray

      public boolean getValueArray(String propertyName, ClockTime timestamp, ClockTime interval, @Nullable MemorySegment @Nullable [] values)

      Gets a number of values for the given controlled property starting at the requested time. The array values need to hold enough space for nValues of the same type as the objects property's type.

      This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample.

      The values are unboxed and ready to be used. The similar function gst_object_get_g_value_array() returns the array as GValues and is better suites for bindings.

      Parameters:
      propertyName - the name of the property to get
      timestamp - the time that should be processed
      interval - the time spacing between subsequent values
      values - array to put control-values in
      Returns:
      true if the given array could be filled, false otherwise

    • hasActiveControlBindings

      public boolean hasActiveControlBindings()
      Check if the this Object has active controlled properties.
      Returns:
      true if the object has active controlled properties

    • hasAncestor

      @Deprecated public boolean hasAncestor(GstObject ancestor)
      Deprecated.

      Use gst_object_has_as_ancestor() instead.

      MT safe. Grabs and releases object's locks.

      Check if this Object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a GstElement is inside a GstPipeline.
      Parameters:
      ancestor - a GstObject to check as ancestor
      Returns:
      true if ancestor is an ancestor of object.

    • hasAsAncestor

      public boolean hasAsAncestor(GstObject ancestor)
      Check if this Object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a GstElement is inside a GstPipeline.
      Parameters:
      ancestor - a GstObject to check as ancestor
      Returns:

      true if ancestor is an ancestor of object.

      MT safe. Grabs and releases object's locks.

    • hasAsParent

      public boolean hasAsParent(GstObject parent)
      Check if parent is the parent of object. E.g. a GstElement can check if it owns a given GstPad.
      Parameters:
      parent - a GstObject to check as parent
      Returns:

      false if either this Object or parent is null. true if parent is the parent of object. Otherwise false.

      MT safe. Grabs and releases object's locks.

      Since:
      1.6

    • ref

      public GstObject ref()

      Increments the reference count on object. This function does not take the lock on this Object because it relies on atomic refcounting.

      This object returns the input parameter to ease writing constructs like : result = gst_object_ref (object->parent);

      Overrides:
      ref in class GObject
      Returns:
      A pointer to this Object

    • removeControlBinding

      public boolean removeControlBinding(ControlBinding binding)
      Removes the corresponding GstControlBinding. If it was the last ref of the binding, it will be disposed.
      Parameters:
      binding - the binding
      Returns:
      true if the binding could be removed.

    • setControlBindingDisabled

      public void setControlBindingDisabled(String propertyName, boolean disabled)
      This function is used to disable the control bindings on a property for some time, i.e. gst_object_sync_values() will do nothing for the property.
      Parameters:
      propertyName - property to disable
      disabled - boolean that specifies whether to disable the controller or not.

    • setControlBindingsDisabled

      public void setControlBindingsDisabled(boolean disabled)
      This function is used to disable all controlled properties of the this Object for some time, i.e. gst_object_sync_values() will do nothing.
      Parameters:
      disabled - boolean that specifies whether to disable the controller or not.

    • setControlRate

      public void setControlRate(ClockTime controlRate)

      Change the control-rate for this object. Audio processing GstElement objects will use this rate to sub-divide their processing loop and call gst_object_sync_values() in between. The length of the processing segment should be up to controlRate nanoseconds.

      The control-rate should not change if the element is in State.PAUSED or State.PLAYING.

      Parameters:
      controlRate - the new control-rate in nanoseconds.

    • setName

      public boolean setName(@Nullable String name)
      Sets the name of object, or gives this Object a guaranteed unique name (if name is null). This function makes a copy of the provided name, so the caller retains ownership of the name it sent.
      Parameters:
      name - new name of object
      Returns:

      true if the name could be set. Since Objects that have a parent cannot be renamed, this function returns false in those cases.

      MT safe. This function grabs and releases object's LOCK.

    • setParent

      public boolean setParent(GstObject parent)
      Sets the parent of this Object to parent. The object's reference count will be incremented, and any floating reference will be removed (see gst_object_ref_sink()).
      Parameters:
      parent - new parent of object
      Returns:

      true if parent could be set or false when this Object already had a parent or this Object and parent are the same.

      MT safe. Grabs and releases object's LOCK.

    • suggestNextSync

      public ClockTime suggestNextSync()
      Returns a suggestion for timestamps where buffers should be split to get best controller results.
      Returns:
      Returns the suggested timestamp or GST_CLOCK_TIME_NONE if no control-rate was set.

    • syncValues

      public boolean syncValues(ClockTime timestamp)

      Sets the properties of the object, according to the GstControlSources that (maybe) handle them and for the given timestamp.

      If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly.

      Parameters:
      timestamp - the time that should be processed
      Returns:
      true if the controller values could be applied to the object properties, false otherwise

    • unparent

      public void unparent()

      Clear the parent of object, removing the associated reference. This function decreases the refcount of object.

      MT safe. Grabs and releases object's lock.

    • unref

      public void unref()

      Decrements the reference count on object. If reference count hits zero, destroy object. This function does not take the lock on this Object as it relies on atomic refcounting.

      The unref method should never be called with the LOCK held since this might deadlock the dispose function.

      Overrides:
      unref in class GObject

    • deepNotify

      protected void deepNotify(GstObject orig, ParamSpec pspec)
      default signal handler

    • onDeepNotify

      public SignalConnection<GstObject.DeepNotifyCallback> onDeepNotify(@Nullable String detail, GstObject.DeepNotifyCallback handler)
      The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin.
      Parameters:
      detail - the signal detail
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDeepNotify

      public void emitDeepNotify(@Nullable String detail, @Nullable GstObject propObject, @Nullable ParamSpec prop)
      Emits the "deep-notify" signal. See onDeepNotify(String, GstObject.DeepNotifyCallback).