Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- addControlBinding
- checkUniqueness
- defaultDeepNotify
- defaultError
- getControlBinding
- getControlRate
- getGValueArray
- getName
- getParent
- getPathString
- getValue
- 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.
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
- newtype Object = Object (ManagedPtr Object)
- class (GObject o, IsDescendantOf Object o) => IsObject o
- toObject :: (MonadIO m, IsObject o) => o -> m Object
- noObject :: Maybe Object
- 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 ()
- objectDefaultError :: (HasCallStack, MonadIO m, IsObject a) => a -> GError -> Maybe Text -> m ()
- objectGetControlBinding :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> m (Maybe ControlBinding)
- objectGetControlRate :: (HasCallStack, MonadIO m, IsObject a) => a -> m Word64
- objectGetGValueArray :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Word64 -> Word64 -> [GValue] -> m Bool
- objectGetName :: (HasCallStack, MonadIO m, IsObject a) => a -> m (Maybe Text)
- objectGetParent :: (HasCallStack, MonadIO m, IsObject a) => a -> m (Maybe Object)
- objectGetPathString :: (HasCallStack, MonadIO m, IsObject a) => a -> m Text
- objectGetValue :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Word64 -> m (Maybe GValue)
- objectHasActiveControlBindings :: (HasCallStack, MonadIO m, IsObject a) => a -> m Bool
- objectHasAncestor :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- objectHasAsAncestor :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- objectHasAsParent :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- objectRef :: (HasCallStack, MonadIO m, IsObject a) => a -> m Object
- 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)
- objectSetControlBindingDisabled :: (HasCallStack, MonadIO m, IsObject a) => a -> Text -> Bool -> m ()
- objectSetControlBindingsDisabled :: (HasCallStack, MonadIO m, IsObject a) => a -> Bool -> m ()
- objectSetControlRate :: (HasCallStack, MonadIO m, IsObject a) => a -> Word64 -> m ()
- objectSetName :: (HasCallStack, MonadIO m, IsObject a) => a -> Maybe Text -> m Bool
- objectSetParent :: (HasCallStack, MonadIO m, IsObject a, IsObject b) => a -> b -> m Bool
- objectSuggestNextSync :: (HasCallStack, MonadIO m, IsObject a) => a -> m Word64
- objectSyncValues :: (HasCallStack, MonadIO m, IsObject a) => a -> Word64 -> m Bool
- objectUnparent :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- objectUnref :: (HasCallStack, MonadIO m, IsObject a) => a -> m ()
- clearObjectName :: (MonadIO m, IsObject o) => o -> m ()
- constructObjectName :: IsObject o => Text -> IO (GValueConstruct o)
- getObjectName :: (MonadIO m, IsObject o) => o -> m (Maybe Text)
- setObjectName :: (MonadIO m, IsObject o) => o -> Text -> m ()
- 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)
- 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 ()
- afterObjectDeepNotify :: (IsObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId
- genClosure_ObjectDeepNotify :: MonadIO m => ObjectDeepNotifyCallback -> m (GClosure C_ObjectDeepNotifyCallback)
- mk_ObjectDeepNotifyCallback :: C_ObjectDeepNotifyCallback -> IO (FunPtr C_ObjectDeepNotifyCallback)
- noObjectDeepNotifyCallback :: Maybe ObjectDeepNotifyCallback
- onObjectDeepNotify :: (IsObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId
- wrap_ObjectDeepNotifyCallback :: ObjectDeepNotifyCallback -> C_ObjectDeepNotifyCallback
Exported types
Memory-managed wrapper type.
Instances
GObject Object Source # | |
Defined in GI.Gst.Objects.Object gobjectType :: IO GType # | |
HasParentTypes Object Source # | |
Defined in GI.Gst.Objects.Object | |
type ParentTypes Object Source # | |
Defined in GI.Gst.Objects.Object |
class (GObject o, IsDescendantOf Object o) => IsObject o Source #
Instances
(GObject o, IsDescendantOf Object o) => IsObject o Source # | |
Defined in GI.Gst.Objects.Object |
Methods
addControlBinding
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's reference count will be incremented, and any floating
reference will be removed (see gst_object_ref_sink()
)
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 string..
The default handler will simply print the error string using g_print.
getControlBinding
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
:: (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
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
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> Text |
|
-> Word64 |
|
-> Word64 |
|
-> [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
getParent
:: (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
:: (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.
hasActiveControlBindings
objectHasActiveControlBindings Source #
:: (HasCallStack, MonadIO m, IsObject a) | |
=> a |
|
-> m Bool | Returns: |
Check if the object
has active controlled properties.
hasAncestor
:: (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
hasAsParent
ref
:: (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
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
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
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
:: (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
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
:: (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
:: (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
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
:: (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
:: (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
:: (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
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 => Text -> IO (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
::deep-notify
signals due to locking issues. In some cases one can use
Bin
::element-added
or Bin
::element-removed
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, IsObject a) => a -> IO (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 C_ObjectDeepNotifyCallback = Ptr () -> Ptr Object -> Ptr GParamSpec -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type ObjectDeepNotifyCallback Source #
= Object |
|
-> GParamSpec |
|
-> 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 -> ObjectDeepNotifyCallback -> m SignalHandlerId Source #
Connect a signal handler for the “deep-notify
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
object #deepNotify callback
genClosure_ObjectDeepNotify :: MonadIO m => ObjectDeepNotifyCallback -> m (GClosure C_ObjectDeepNotifyCallback) Source #
Wrap the callback into a GClosure
.
mk_ObjectDeepNotifyCallback :: C_ObjectDeepNotifyCallback -> IO (FunPtr C_ObjectDeepNotifyCallback) Source #
Generate a function pointer callable from C code, from a C_ObjectDeepNotifyCallback
.
noObjectDeepNotifyCallback :: Maybe ObjectDeepNotifyCallback Source #
A convenience synonym for
.Nothing
:: Maybe
ObjectDeepNotifyCallback
onObjectDeepNotify :: (IsObject a, MonadIO m) => a -> ObjectDeepNotifyCallback -> m SignalHandlerId Source #
Connect a signal handler for the “deep-notify
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
object #deepNotify callback