Package org.freedesktop.gstreamer.gst

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("io.github.jwharm.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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GstObject.Builder<B extends GstObject.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	GstObject.DeepNotifyCallback	Functional interface declaration of the DeepNotifyCallback callback.
static class	GstObject.Object$Impl	The Object$Impl type represents a native instance of the abstract GstObject class.
static class	GstObject.ObjectClass	GStreamer base object class.

Nested classes/interfaces inherited from class org.gnome.gobject.InitiallyUnowned

InitiallyUnowned.InitiallyUnownedClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback

Constructor Summary

Constructors

Constructor	Description
GstObject()	Creates a new GstObject.
GstObject(MemorySegment address)	Create a GstObject proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
boolean	addControlBinding(ControlBinding binding)	Attach the GstControlBinding to the object.
protected GstObject	asParent()	Returns this instance as if it were its parent type.
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.
protected void	deepNotify(GstObject orig, ParamSpec pspec)	default signal handler
static void	defaultDeepNotify(GObject object, GstObject orig, ParamSpec pspec, @Nullable String @Nullable [] excludedProps)	A default deep_notify signal callback for an object.
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..
void	emitDeepNotify(@Nullable String detail, @Nullable GstObject propObject, @Nullable ParamSpec prop)	Emits the "deep-notify" signal.
@Nullable ControlBinding	getControlBinding(String propertyName)	Gets the corresponding GstControlBinding for the property.
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.
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.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
@Nullable String	getName()	Returns a copy of the name of object. Caller should g_free() the return value after usage.
@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.
String	getPathString()	Generates a string describing the path of this Object in the object hierarchy.
static @Nullable Type	getType()	Get the GType of the GstObject class
@Nullable Value	getValue(String propertyName, ClockTime timestamp)	Gets the value for the given controlled property at the requested time.
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.
boolean	hasActiveControlBindings()	Check if the this Object has active controlled properties.
boolean	hasAncestor(GstObject ancestor)	Deprecated. Use gst_object_has_as_ancestor() instead.
boolean	hasAsAncestor(GstObject ancestor)	Check if this Object has an ancestor ancestor somewhere up in the hierarchy.
boolean	hasAsParent(GstObject parent)	Check if parent is the parent of object. E.g.
SignalConnection<GstObject.DeepNotifyCallback>	onDeepNotify(@Nullable String detail, GstObject.DeepNotifyCallback handler)	The deep notify signal is used to be notified of property changes.
GstObject	ref()	Increments the reference count on object. This function does not take the lock on this Object because it relies on atomic refcounting.
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.
boolean	removeControlBinding(ControlBinding binding)	Removes the corresponding GstControlBinding.
static boolean	replace(@Nullable Out<GstObject> oldobj, @Nullable GstObject newobj)	Atomically modifies a pointer to point to a new object.
void	setControlBindingDisabled(String propertyName, boolean disabled)	This function is used to disable the control bindings on a property for some time, i.e.
void	setControlBindingsDisabled(boolean disabled)	This function is used to disable all controlled properties of the this Object for some time, i.e.
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.
boolean	setName(@Nullable String name)	Sets the name of object, or gives this Object a guaranteed unique name (if name is null).
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()).
ClockTime	suggestNextSync()	Returns a suggestion for timestamps where buffers should be split to get best controller results.
boolean	syncValues(ClockTime timestamp)	Sets the properties of the object, according to the GstControlSources that (maybe) handle them and for the given timestamp.
void	unparent()	Clear the parent of object, removing the associated reference.
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.

Methods inherited from class org.gnome.gobject.InitiallyUnowned

builder

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GstObject

public GstObject(MemorySegment address)

Create a GstObject proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

GstObject

public GstObject()

Creates 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()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class InitiallyUnowned

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:

• GstObject.DeepNotifyCallback.run(org.freedesktop.gstreamer.gst.GstObject, org.gnome.gobject.ParamSpec)

emitDeepNotify

public void emitDeepNotify(@Nullable String detail,
 @Nullable GstObject propObject,
 @Nullable ParamSpec prop)

Emits the "deep-notify" signal. See onDeepNotify(java.lang.String, org.freedesktop.gstreamer.gst.GstObject.DeepNotifyCallback).