gi-gst-1.0.26: GStreamer bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Gst.Objects.Object

Description

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

Object 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 Object which is Object (e.g. objectRef becomes objectRef).

Since Object derives from InitiallyUnowned, it also inherits the floating reference. Be aware that functions such as binAdd and elementAddPad take ownership of the floating reference.

In contrast to Object instances, Object adds a name property. The functions objectSetName and objectGetName 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 Element? 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 ControlSource. csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
  • Attach the ControlSource 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
Synopsis

Exported types

newtype Object Source #

Memory-managed wrapper type.

Constructors

Object (ManagedPtr Object) 

Instances

Instances details
Eq Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

Methods

(==) :: Object -> Object -> Bool #

(/=) :: Object -> Object -> Bool #

GObject Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

ManagedPtrNewtype Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

Methods

toManagedPtr :: Object -> ManagedPtr Object

TypedObject Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

Methods

glibType :: IO GType

HasParentTypes Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

IsGValue (Maybe Object) Source #

Convert Object to and from GValue. See toGValue and fromGValue.

Instance details

Defined in GI.Gst.Objects.Object

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Object -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Object)

type ParentTypes Object Source # 
Instance details

Defined in GI.Gst.Objects.Object

type ParentTypes Object = '[Object]

class (GObject o, IsDescendantOf Object o) => IsObject o Source #

Type class for types which can be safely cast to Object, for instance with toObject.

Instances

Instances details
(GObject o, IsDescendantOf Object o) => IsObject o Source # 
Instance details

Defined in GI.Gst.Objects.Object

toObject :: (MonadIO m, IsObject o) => o -> m Object Source #

Cast to Object, for types for which this is known to be safe. For general casts, use castTo.

Methods

addControlBinding

objectAddControlBinding Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) 
=> a

object: the controller object

-> b

binding: the ControlBinding that should be used

-> m Bool

Returns: False if the given binding has not been setup for this object or has been setup for a non suitable property, True otherwise.

Attach the ControlBinding to the object. If there already was a ControlBinding 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())

checkUniqueness

objectCheckUniqueness Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> [a]

list: a list of Object to check through

-> Text

name: the name to search for

-> m Bool

Returns: True if a Object named name does not appear in list, False if it does.

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

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 Object in the list to compare the name, so be careful when passing a list with a locked object.

defaultDeepNotify

objectDefaultDeepNotify Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> a

object: the Object that signalled the notify.

-> b

orig: a Object that initiated the notify.

-> GParamSpec

pspec: a ParamSpec of the property.

-> Maybe [Text]

excludedProps: a set of user-specified properties to exclude or Nothing to show all changes.

-> m () 

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.

defaultError

objectDefaultError Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

source: the Object that initiated the error.

-> GError

error: the GError.

-> Maybe Text

debug: an additional debug information string, or Nothing

-> m () 

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.

getControlBinding

objectGetControlBinding Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object

-> Text

propertyName: name of the property

-> m (Maybe ControlBinding)

Returns: the ControlBinding for propertyName or Nothing if the property is not controlled.

Gets the corresponding ControlBinding for the property. This should be unreferenced again after use.

getControlRate

objectGetControlRate Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> m Word64

Returns: the control rate in nanoseconds

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

If the object is not under property control, this will return 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 StatePaused or StatePlaying.

getGValueArray

objectGetGValueArray Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Text

propertyName: the name of the property to get

-> Word64

timestamp: the time that should be processed

-> Word64

interval: the time spacing between subsequent values

-> [GValue]

values: array to put control-values in

-> m Bool

Returns: True if the given array could be filled, False otherwise

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 Value.

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.

getName

objectGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object

-> m (Maybe Text)

Returns: the name of object. free after usage.

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

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

Free-function: g_free

getParent

objectGetParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object

-> m (Maybe Object)

Returns: parent of object, this can be Nothing if object has no parent. unref after usage.

MT safe. Grabs and releases object's LOCK.

Returns the parent of object. This function increases the refcount of the parent object so you should objectUnref it after usage.

getPathString

objectGetPathString Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object

-> m Text

Returns: a string describing the path of object. You must free the string after usage.

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

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

Free-function: g_free

getValue

objectGetValue Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Text

propertyName: the name of the property to get

-> Word64

timestamp: the time the control-change should be read from

-> m (Maybe GValue)

Returns: the GValue of the property at the given time, or Nothing if the property isn't controlled.

Gets the value for the given controlled property at the requested time.

hasActiveControlBindings

objectHasActiveControlBindings Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> m Bool

Returns: True if the object has active controlled properties

Check if the object has active controlled properties.

hasAncestor

objectHasAncestor Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> a

object: a Object to check

-> b

ancestor: a Object to check as ancestor

-> m Bool

Returns: True if ancestor is an ancestor of object.

Deprecated: Use objectHasAsAncestor instead.MT safe. Grabs and releases object's locks.

Check if object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

hasAsAncestor

objectHasAsAncestor Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> a

object: a Object to check

-> b

ancestor: a Object to check as ancestor

-> m Bool

Returns: True if ancestor is an ancestor of object.

MT safe. Grabs and releases object's locks.

Check if object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

hasAsParent

objectHasAsParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> a

object: a Object to check

-> b

parent: a Object to check as parent

-> m Bool

Returns: False if either object or parent is Nothing. True if parent is the parent of object. Otherwise False.

MT safe. Grabs and releases object's locks.

Check if parent is the parent of object. E.g. a Element can check if it owns a given Pad.

Since: 1.6

ref

objectRef Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object to reference

-> m Object

Returns: A pointer to object

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

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

removeControlBinding

objectRemoveControlBinding Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) 
=> a

object: the object

-> b

binding: the binding

-> m Bool

Returns: True if the binding could be removed.

Removes the corresponding ControlBinding. If it was the last ref of the binding, it will be disposed.

replace

objectReplace Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> Maybe a

oldobj: pointer to a place of a Object to replace

-> Maybe b

newobj: a new Object

-> m (Bool, Maybe Object)

Returns: True if newobj was different from oldobj

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 Nothing.

setControlBindingDisabled

objectSetControlBindingDisabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Text

propertyName: property to disable

-> Bool

disabled: boolean that specifies whether to disable the controller or not.

-> m () 

This function is used to disable the control bindings on a property for some time, i.e. objectSyncValues will do nothing for the property.

setControlBindingsDisabled

objectSetControlBindingsDisabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Bool

disabled: boolean that specifies whether to disable the controller or not.

-> m () 

This function is used to disable all controlled properties of the object for some time, i.e. objectSyncValues will do nothing.

setControlRate

objectSetControlRate Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Word64

controlRate: the new control-rate in nanoseconds.

-> m () 

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

The control-rate should not change if the element is in StatePaused or StatePlaying.

setName

objectSetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object

-> Maybe Text

name: new name of object

-> m Bool

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.

Sets the name of object, or gives object a guaranteed unique name (if name is Nothing). This function makes a copy of the provided name, so the caller retains ownership of the name it sent.

setParent

objectSetParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsObject b) 
=> a

object: a Object

-> b

parent: new parent of object

-> m Bool

Returns: True if parent could be set or False when object already had a parent or object and parent are the same.

MT safe. Grabs and releases object's LOCK.

Sets the parent of object to parent. The object's reference count will be incremented, and any floating reference will be removed (see gst_object_ref_sink()).

suggestNextSync

objectSuggestNextSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> m Word64

Returns: Returns the suggested timestamp or CLOCK_TIME_NONE if no control-rate was set.

Returns a suggestion for timestamps where buffers should be split to get best controller results.

syncValues

objectSyncValues Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: the object that has controlled properties

-> Word64

timestamp: the time that should be processed

-> m Bool

Returns: True if the controller values could be applied to the object properties, False otherwise

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.

unparent

objectUnparent Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object to unparent

-> m () 

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

objectUnref Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> a

object: a Object to unreference

-> m () 

Decrements the reference count on object. If reference count hits zero, destroy object. This function does not take the lock on 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.

Properties

name

No description available in the introspection data.

clearObjectName :: (MonadIO m, IsObject o) => o -> m () Source #

Set the value of the “name” property to Nothing. When overloading is enabled, this is equivalent to

clear #name

constructObjectName :: (IsObject o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “name” property. This is rarely needed directly, but it is used by new.

getObjectName :: (MonadIO m, IsObject o) => o -> m (Maybe Text) Source #

Get the value of the “name” property. When overloading is enabled, this is equivalent to

get object #name

setObjectName :: (MonadIO m, IsObject o) => o -> Text -> m () Source #

Set the value of the “name” property. When overloading is enabled, this is equivalent to

set object [ #name := value ]

parent

The parent of the object. Please note, that when changing the 'parent' property, we don't emit Object::notify and Object::deepNotify signals due to locking issues. In some cases one can use Bin::elementAdded or Bin::elementRemoved signals on the parent to achieve a similar effect.

clearObjectParent :: (MonadIO m, IsObject o) => o -> m () Source #

Set the value of the “parent” property to Nothing. When overloading is enabled, this is equivalent to

clear #parent

constructObjectParent :: (IsObject o, MonadIO m, IsObject a) => a -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “parent” property. This is rarely needed directly, but it is used by new.

getObjectParent :: (MonadIO m, IsObject o) => o -> m (Maybe Object) Source #

Get the value of the “parent” property. When overloading is enabled, this is equivalent to

get object #parent

setObjectParent :: (MonadIO m, IsObject o, IsObject a) => o -> a -> m () Source #

Set the value of the “parent” property. When overloading is enabled, this is equivalent to

set object [ #parent := value ]

Signals

deepNotify

type ObjectDeepNotifyCallback Source #

Arguments

 = Object

propObject: the object that originated the signal

-> GParamSpec

prop: the property that changed

-> IO () 

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.

afterObjectDeepNotify :: (IsObject a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => ObjectDeepNotifyCallback) -> m SignalHandlerId Source #

Connect a signal handler for the deepNotify signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after object #deepNotify callback

This signal admits a optional parameter detail. If it's not Nothing, we will connect to “deep-notify::detail” instead.

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onObjectDeepNotify :: (IsObject a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => ObjectDeepNotifyCallback) -> m SignalHandlerId Source #

Connect a signal handler for the deepNotify signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on object #deepNotify callback

This signal admits a optional parameter detail. If it's not Nothing, we will connect to “deep-notify::detail” instead.