Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- addControlBinding
- checkUniqueness
- defaultDeepNotify
- defaultError
- getControlBinding
- getControlRate
- getGValueArray
- getName
- getParent
- getPathString
- getValue
- getValueArray
- hasActiveControlBindings
- hasAncestor
- hasAsAncestor
- hasAsParent
- ref
- removeControlBinding
- replace
- setControlBindingDisabled
- setControlBindingsDisabled
- setControlRate
- setName
- setParent
- suggestNextSync
- syncValues
- unparent
- unref
- Properties
- Signals
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.
<refsect2> <title>controlled properties</title> <para> 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!
<orderedlist>
<listitem><para>
mark gobject-properties paramspecs that make sense to be controlled,
by GST_PARAM_CONTROLLABLE.
</para></listitem>
<listitem><para>
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.
</para></listitem>
</orderedlist>
What needs to be done in applications?
Again it's not a lot to change.
<orderedlist>
<listitem><para>
create a ControlSource
.
csource = gst_interpolation_control_source_new ();
g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
</para></listitem>
<listitem><para>
Attach the ControlSource
on the controller to a property.
gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
</para></listitem>
<listitem><para>
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);
</para></listitem>
<listitem><para>
start your pipeline
</para></listitem>
</orderedlist>
</para>
</refsect2>
- newtype Object = Object (ManagedPtr Object)
- class GObject o => IsObject o
- toObject :: IsObject o => o -> IO Object
- noObject :: Maybe Object
- data ObjectAddControlBindingMethodInfo
- objectAddControlBinding :: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) => a -> b -> m Bool
- objectCheckUniqueness :: (HasCallStack, MonadIO m, IsObject a) => [a] -> Text -> m Bool
- objectDefaultDeepNotify :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> GParamSpec -> Maybe [Text] -> m ()
- data ObjectDefaultErrorMethodInfo
- objectDefaultError :: (HasCallStack, MonadIO m, IsObject a) => a -> GError -> Maybe Text -> m ()
- data ObjectGetControlBindingMethodInfo
- objectGetControlBinding :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> m (Maybe ControlBinding)
- data ObjectGetControlRateMethodInfo
- objectGetControlRate :: (HasCallStack, MonadIO m, IsObject a) => a -> m Word64
- data ObjectGetGValueArrayMethodInfo
- objectGetGValueArray :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Word64 -> Word64 -> Word32 -> GValue -> m Bool
- data ObjectGetNameMethodInfo
- objectGetName :: (HasCallStack, MonadIO m, IsObject a) => a -> m (Maybe Text)
- data ObjectGetParentMethodInfo
- objectGetParent :: (HasCallStack, MonadIO m, IsObject a) => a -> m (Maybe Object)
- data ObjectGetPathStringMethodInfo
- objectGetPathString :: (HasCallStack, MonadIO m, IsObject a) => a -> m Text
- data ObjectGetValueMethodInfo
- objectGetValue :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Word64 -> m (Maybe GValue)
- data ObjectGetValueArrayMethodInfo
- objectGetValueArray :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Word64 -> Word64 -> Word32 -> Ptr () -> m Bool
- data ObjectHasActiveControlBindingsMethodInfo
- objectHasActiveControlBindings :: (HasCallStack, MonadIO m, IsObject a) => a -> m Bool
- data ObjectHasAncestorMethodInfo
- objectHasAncestor :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- data ObjectHasAsAncestorMethodInfo
- objectHasAsAncestor :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- data ObjectHasAsParentMethodInfo
- objectHasAsParent :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- data ObjectRefMethodInfo
- objectRef :: (HasCallStack, MonadIO m, IsObject a) => a -> m Object
- data ObjectRemoveControlBindingMethodInfo
- objectRemoveControlBinding :: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) => a -> b -> m Bool
- objectReplace :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => Maybe a -> Maybe b -> m (Bool, Maybe Object)
- data ObjectSetControlBindingDisabledMethodInfo
- objectSetControlBindingDisabled :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Bool -> m ()
- data ObjectSetControlBindingsDisabledMethodInfo
- objectSetControlBindingsDisabled :: (HasCallStack, MonadIO m, IsObject a) => a -> Bool -> m ()
- data ObjectSetControlRateMethodInfo
- objectSetControlRate :: (HasCallStack, MonadIO m, IsObject a) => a -> Word64 -> m ()
- data ObjectSetNameMethodInfo
- objectSetName :: (HasCallStack, MonadIO m, IsObject a) => a -> Maybe Text -> m Bool
- data ObjectSetParentMethodInfo
- objectSetParent :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- data ObjectSuggestNextSyncMethodInfo
- objectSuggestNextSync :: (HasCallStack, MonadIO m, IsObject a) => a -> m Word64
- data ObjectSyncValuesMethodInfo
- objectSyncValues :: (HasCallStack, MonadIO m, IsObject a) => a -> Word64 -> m Bool
- data ObjectUnparentMethodInfo
- objectUnparent :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectUnrefMethodInfo
- objectUnref :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- data ObjectNamePropertyInfo
- clearObjectName :: (MonadIO m, IsObject o) => o -> m ()
- constructObjectName :: IsObject o => Text -> IO (GValueConstruct o)
- getObjectName :: (MonadIO m, IsObject o) => o -> m (Maybe Text)
- objectName :: AttrLabelProxy "name"
- setObjectName :: (MonadIO m, IsObject o) => o -> Text -> m ()
- data ObjectParentPropertyInfo
- clearObjectParent :: (MonadIO m, IsObject o) => o -> m ()
- constructObjectParent :: (IsObject o, IsObject a) => a -> IO (GValueConstruct o)
- getObjectParent :: (MonadIO m, IsObject o) => o -> m (Maybe Object)
- objectParent :: AttrLabelProxy "parent"
- setObjectParent :: (MonadIO m, IsObject o, IsObject a) => o -> a -> m ()
- type C_ObjectDeepNotifyCallback = Ptr () -> Ptr Object -> Ptr GParamSpec -> Ptr () -> IO ()
- type ObjectDeepNotifyCallback = Object -> GParamSpec -> IO ()
- data ObjectDeepNotifySignalInfo
- afterObjectDeepNotify :: (GObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId
- genClosure_ObjectDeepNotify :: ObjectDeepNotifyCallback -> IO Closure
- mk_ObjectDeepNotifyCallback :: C_ObjectDeepNotifyCallback -> IO (FunPtr C_ObjectDeepNotifyCallback)
- noObjectDeepNotifyCallback :: Maybe ObjectDeepNotifyCallback
- onObjectDeepNotify :: (GObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId
- wrap_ObjectDeepNotifyCallback :: ObjectDeepNotifyCallback -> Ptr () -> Ptr Object -> Ptr GParamSpec -> Ptr () -> IO ()
Exported types
GObject Object Source # | |
IsObject Object Source # | |
IsObject Object Source # | |
((~) * info (ResolveObjectMethod t Object), MethodInfo * info Object p) => IsLabel t (Object -> p) Source # | |
((~) * info (ResolveObjectMethod t Object), MethodInfo * info Object p) => IsLabelProxy t (Object -> p) Source # | |
HasAttributeList * Object Source # | |
type AttributeList Object Source # | |
type SignalList Object Source # | |
class GObject o => IsObject o Source #
Methods
addControlBinding
data ObjectAddControlBindingMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsControlBinding b) => MethodInfo * ObjectAddControlBindingMethodInfo a signature Source # | |
objectAddControlBinding Source #
:: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
Attach the ControlBinding
to the object. If there already was a
ControlBinding
for this property it will be replaced.
The object
will take ownership of the binding
.
checkUniqueness
objectCheckUniqueness Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> [a] |
|
-> Text |
|
-> m Bool | Returns: 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 #
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> a |
|
-> b |
|
-> GParamSpec |
|
-> Maybe [Text] |
|
-> 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
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> GError |
|
-> Maybe Text |
|
-> m () |
A default error function that uses g_printerr()
to display the error message
and the optional debug sting..
The default handler will simply print the error string using g_print.
getControlBinding
data ObjectGetControlBindingMethodInfo Source #
((~) * signature (Text -> m (Maybe ControlBinding)), MonadIO m, IsObject a) => MethodInfo * ObjectGetControlBindingMethodInfo a signature Source # | |
objectGetControlBinding Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> m (Maybe ControlBinding) | Returns: the |
Gets the corresponding ControlBinding
for the property. This should be
unreferenced again after use.
getControlRate
data ObjectGetControlRateMethodInfo Source #
((~) * signature (m Word64), MonadIO m, IsObject a) => MethodInfo * ObjectGetControlRateMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> 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
inbetween. 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
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Word64 |
|
-> Word64 |
|
-> Word32 |
|
-> GValue |
|
-> m Bool | Returns: |
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
data ObjectGetNameMethodInfo Source #
((~) * signature (m (Maybe Text)), MonadIO m, IsObject a) => MethodInfo * ObjectGetNameMethodInfo a signature Source # | |
getParent
data ObjectGetParentMethodInfo Source #
((~) * signature (m (Maybe Object)), MonadIO m, IsObject a) => MethodInfo * ObjectGetParentMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m (Maybe Object) | Returns: parent of MT safe. Grabs and releases |
Returns the parent of object
. This function increases the refcount
of the parent object so you should objectUnref
it after usage.
getPathString
data ObjectGetPathStringMethodInfo Source #
((~) * signature (m Text), MonadIO m, IsObject a) => MethodInfo * ObjectGetPathStringMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Text | Returns: a string describing the path of MT safe. Grabs and releases the 'GI.Gst.Objects.Object.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
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Word64 |
|
-> m (Maybe GValue) | Returns: the GValue of the property at the given time,
or |
Gets the value for the given controlled property at the requested time.
getValueArray
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Word64 |
|
-> Word64 |
|
-> Word32 |
|
-> Ptr () |
|
-> m Bool | Returns: |
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
objectGetGValueArray
returns the array as GValues
and is
better suites for bindings.
hasActiveControlBindings
data ObjectHasActiveControlBindingsMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsObject a) => MethodInfo * ObjectHasActiveControlBindingsMethodInfo a signature Source # | |
objectHasActiveControlBindings Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Bool | Returns: |
Check if the object
has active controlled properties.
hasAncestor
data ObjectHasAncestorMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectHasAncestorMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
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
data ObjectHasAsAncestorMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectHasAsAncestorMethodInfo a signature Source # | |
hasAsParent
data ObjectHasAsParentMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectHasAsParentMethodInfo a signature Source # | |
ref
data ObjectRefMethodInfo Source #
((~) * signature (m Object), MonadIO m, IsObject a) => MethodInfo * ObjectRefMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Object | Returns: A pointer to |
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
data ObjectRemoveControlBindingMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsControlBinding b) => MethodInfo * ObjectRemoveControlBindingMethodInfo a signature Source # | |
objectRemoveControlBinding Source #
:: (HasCallStack, MonadIO m, IsObject a, IsControlBinding b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
Removes the corresponding ControlBinding
. If it was the
last ref of the binding, it will be disposed.
replace
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> Maybe a |
|
-> Maybe b |
|
-> m (Bool, Maybe Object) | Returns: |
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
data ObjectSetControlBindingDisabledMethodInfo Source #
((~) * signature (Text -> Bool -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectSetControlBindingDisabledMethodInfo a signature Source # | |
objectSetControlBindingDisabled Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Bool |
|
-> 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
data ObjectSetControlBindingsDisabledMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectSetControlBindingsDisabledMethodInfo a signature Source # | |
objectSetControlBindingsDisabled Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Bool |
|
-> m () |
This function is used to disable all controlled properties of the object
for
some time, i.e. objectSyncValues
will do nothing.
setControlRate
data ObjectSetControlRateMethodInfo Source #
((~) * signature (Word64 -> m ()), MonadIO m, IsObject a) => MethodInfo * ObjectSetControlRateMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Word64 |
|
-> 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
inbetween. 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
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Maybe Text |
|
-> m Bool | Returns: MT safe. This function grabs and releases |
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
data ObjectSetParentMethodInfo Source #
((~) * signature (b -> m Bool), MonadIO m, IsObject a, IsObject b) => MethodInfo * ObjectSetParentMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a, IsObject b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: MT safe. Grabs and releases |
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
data ObjectSuggestNextSyncMethodInfo Source #
((~) * signature (m Word64), MonadIO m, IsObject a) => MethodInfo * ObjectSuggestNextSyncMethodInfo a signature Source # | |
objectSuggestNextSync Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Word64 | Returns: Returns the suggested timestamp or |
Returns a suggestion for timestamps where buffers should be split to get best controller results.
syncValues
data ObjectSyncValuesMethodInfo Source #
((~) * signature (Word64 -> m Bool), MonadIO m, IsObject a) => MethodInfo * ObjectSyncValuesMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Word64 |
|
-> m Bool | Returns: |
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
data ObjectUnparentMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectUnparentMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> 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
data ObjectUnrefMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsObject a) => MethodInfo * ObjectUnrefMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> 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
data ObjectNamePropertyInfo Source #
clearObjectName :: (MonadIO m, IsObject o) => o -> m () Source #
constructObjectName :: IsObject o => Text -> IO (GValueConstruct o) Source #
objectName :: AttrLabelProxy "name" Source #
parent
data ObjectParentPropertyInfo Source #
clearObjectParent :: (MonadIO m, IsObject o) => o -> m () Source #
constructObjectParent :: (IsObject o, IsObject a) => a -> IO (GValueConstruct o) Source #
objectParent :: AttrLabelProxy "parent" Source #
Signals
deepNotify
type C_ObjectDeepNotifyCallback = Ptr () -> Ptr Object -> Ptr GParamSpec -> Ptr () -> IO () Source #
type ObjectDeepNotifyCallback = Object -> GParamSpec -> IO () Source #
afterObjectDeepNotify :: (GObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId Source #
mk_ObjectDeepNotifyCallback :: C_ObjectDeepNotifyCallback -> IO (FunPtr C_ObjectDeepNotifyCallback) Source #
onObjectDeepNotify :: (GObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId Source #
wrap_ObjectDeepNotifyCallback :: ObjectDeepNotifyCallback -> Ptr () -> Ptr Object -> Ptr GParamSpec -> Ptr () -> IO () Source #