Portability | portable (depends on GHC) |
---|---|
Stability | alpha |
Maintainer | gtk2hs-devel@lists.sourceforge.net |
Safe Haskell | Safe-Infered |
Abstract class of pipeline elements.
- data Element
- class ObjectClass o => ElementClass o
- castToElement :: GObjectClass obj => obj -> Element
- gTypeElement :: GType
- data ElementFlags
- data State
- data StateChange
- data StateChangeReturn
- elementAddPad :: (ElementClass elementT, PadClass padT) => elementT -> padT -> IO Bool
- elementGetCompatiblePad :: (ElementClass elementT, PadClass padT) => elementT -> padT -> Caps -> IO (Maybe Pad)
- elementGetCompatiblePadTemplate :: (ElementClass elementT, PadTemplateClass padTemplateT) => elementT -> padTemplateT -> IO (Maybe PadTemplate)
- elementGetRequestPad :: ElementClass elementT => elementT -> String -> IO (Maybe Pad)
- elementGetStaticPad :: ElementClass elementT => elementT -> String -> IO (Maybe Pad)
- elementReleaseRequestPad :: (ElementClass elementT, PadClass padT) => elementT -> padT -> IO ()
- elementRemovePad :: (ElementClass elementT, PadClass padT) => elementT -> padT -> IO Bool
- elementIteratePads :: ElementClass elementT => elementT -> IO (Iterator Pad)
- elementIterateSinkPads :: ElementClass elementT => elementT -> IO (Iterator Pad)
- elementIterateSrcPads :: ElementClass elementT => elementT -> IO (Iterator Pad)
- elementLink :: (ElementClass srcT, ElementClass sinkT) => srcT -> sinkT -> IO Bool
- elementUnlink :: (ElementClass srcT, ElementClass sinkT) => srcT -> sinkT -> IO ()
- elementLinkPads :: (ElementClass srcT, ElementClass sinkT) => srcT -> Maybe String -> sinkT -> Maybe String -> IO Bool
- elementUnlinkPads :: (ElementClass srcT, ElementClass sinkT) => srcT -> String -> sinkT -> String -> IO ()
- elementLinkPadsFiltered :: (ElementClass srcT, ElementClass sinkT) => srcT -> Maybe String -> sinkT -> Maybe String -> Caps -> IO Bool
- elementLinkFiltered :: (ElementClass srcT, ElementClass sinkT) => srcT -> sinkT -> Maybe Caps -> IO Bool
- elementSetBaseTime :: ElementClass elementT => elementT -> ClockTimeDiff -> IO ()
- elementGetBaseTime :: ElementClass elementT => elementT -> IO ClockTimeDiff
- elementSetBus :: (ElementClass elementT, BusClass busT) => elementT -> busT -> IO ()
- elementGetBus :: ElementClass elementT => elementT -> IO Bus
- elementGetFactory :: ElementClass elementT => elementT -> IO ElementFactory
- elementSetIndex :: (ElementClass elementT, IndexClass indexT) => elementT -> indexT -> IO ()
- elementIsIndexable :: ElementClass elementT => elementT -> IO Bool
- elementRequiresClock :: ElementClass elementT => elementT -> IO Bool
- elementSetClock :: (ElementClass elementT, ClockClass clockT) => elementT -> clockT -> IO Bool
- elementGetClock :: ElementClass elementT => elementT -> IO (Maybe Clock)
- elementProvidesClock :: ElementClass elementT => elementT -> IO Bool
- elementProvideClock :: ElementClass elementT => elementT -> IO (Maybe Clock)
- elementSetState :: ElementClass elementT => elementT -> State -> IO StateChangeReturn
- elementGetState :: ElementClass elementT => elementT -> ClockTime -> IO (StateChangeReturn, Maybe State, Maybe State)
- elementSetLockedState :: ElementClass elementT => elementT -> Bool -> IO Bool
- elementIsLockedState :: ElementClass elementT => elementT -> IO Bool
- elementAbortState :: ElementClass elementT => elementT -> IO ()
- elementStateGetName :: State -> String
- elementStateChangeReturnGetName :: StateChangeReturn -> String
- elementSyncStateWithParent :: ElementClass elementT => elementT -> IO Bool
- elementGetQueryTypes :: ElementClass element => element -> IO [QueryType]
- elementQuery :: (ElementClass element, QueryClass query) => element -> query -> IO Bool
- elementQueryConvert :: ElementClass element => element -> Format -> Int64 -> Format -> IO (Maybe (Format, Word64))
- elementQueryPosition :: ElementClass element => element -> Format -> IO (Maybe (Format, Word64))
- elementQueryDuration :: ElementClass element => element -> Format -> IO (Maybe (Format, Word64))
- elementSendEvent :: (ElementClass element, EventClass event) => element -> event -> IO Bool
- elementSeekSimple :: ElementClass element => element -> Format -> [SeekFlags] -> Int64 -> IO Bool
- elementSeek :: ElementClass element => element -> Double -> Format -> [SeekFlags] -> SeekType -> Int64 -> SeekType -> Int64 -> IO Bool
- elementNoMorePads :: ElementClass element => Signal element (IO ())
- elementPadAdded :: ElementClass element => Signal element (Pad -> IO ())
- elementPadRemoved :: ElementClass element => Signal element (Pad -> IO ())
Detail
Element
is the abstract base class needed to construct an
element that can be used in a GStreamer pipeline.
All elements have pads (of the type Pad
). These pads link to
pads on other elements. Buffer
s flow between these linked
pads. An Element
has a Pad
for each input (or sink) and
output (or source).
An element's pad can be retrieved by name with
elementGetStaticPad
or elementGetRequestPad
. An Iterator
over all an element's pads can be retrieved with
elementIteratePads
.
Elements can be linked through their pads. If the link is
straightforward, use the elementLink
convenience function to
link two elements. Use elementLinkFiltered
to link two
elements constrained by a specified set of Caps
. For finer
control, use elementLinkPads
and elementLinkPadsFiltered
to
specify the pads to link on each element by name.
Each element has a State
. You can get and set the state of an
element with elementGetState
and elementSetState
. To get a
string representation of a State
, use elementStateGetName
.
You can get and set a Clock
on an element using
elementGetClock
and elementSetClock
. Some elements can
provide a clock for the pipeline if elementProvidesClock
returns True
. With the elementProvideClock
method one can
retrieve the clock provided by such an element. Not all
elements require a clock to operate correctly. If
elementRequiresClock
returns True
, a clock should be set on
the element with elementSetClock
.
Note that clock slection and distribution is normally handled
by the toplevel Pipeline
so the clock functions should only
be used in very specific situations.
Types
class ObjectClass o => ElementClass o Source
castToElement :: GObjectClass obj => obj -> ElementSource
data ElementFlags Source
The flags that an Element
may have.
ElementLockedState | parent state changes are ignored |
ElementIsSink | the element is a sink |
ElementUnparenting | child is being removed from the parent bin |
data StateChange Source
The different state changes that are passed to the state change
functions of Element
s.
StateChangeNullToReady | state change from |
StateChangeReadyToPaused | state change from |
StateChangePausedToPlaying | state change from |
StateChangePlayingToPaused | state change from |
StateChangePausedToReady | state change from |
StateChangeReadyToNull | state change from |
data StateChangeReturn Source
Element Operations
:: (ElementClass elementT, PadClass padT) | |
=> elementT |
|
-> padT |
|
-> IO Bool |
Add a pad (link point) to an element. The pad's parent will be set to
element
.
Pads are not automatically activated so elements should perform
the needed steps to activate the pad in case this pad is added in
the StatePaused
or StatePlaying
state. See padSetActive
for
more information about activating pads.
This function will emit the elementPadAdded
signal on the
element.
:: (ElementClass elementT, PadClass padT) | |
=> elementT |
|
-> padT |
|
-> Caps |
|
-> IO (Maybe Pad) | a |
Look for an unlinked pad to which the pad
can link. It is not
guaranteed that linking the pads will work, though it should work in most
cases.
elementGetCompatiblePadTemplateSource
:: (ElementClass elementT, PadTemplateClass padTemplateT) | |
=> elementT |
|
-> padTemplateT |
|
-> IO (Maybe PadTemplate) | the compatible |
Retrieve a pad template from element
that is compatible with
padTemplate
. Pads from compatible templates can be linked
together.
:: ElementClass elementT | |
=> elementT |
|
-> String |
|
-> IO (Maybe Pad) |
Retrieve a pad from the element by name. This version only
retrieves request pads. The pad should be released with
elementReleaseRequestPad
.
:: ElementClass elementT | |
=> elementT |
|
-> String |
|
-> IO (Maybe Pad) |
Retreive a pad from element
by name. This version only
retrieves already-existing (i.e. static) pads.
elementReleaseRequestPadSource
:: (ElementClass elementT, PadClass padT) | |
=> elementT |
|
-> padT |
|
-> IO () |
Release a request pad that was previously obtained with
elementGetRequestPad
.
:: (ElementClass elementT, PadClass padT) | |
=> elementT |
|
-> padT |
|
-> IO Bool |
Remove pad
from element
.
This function is used by plugin developers and should not be used
by applications. Pads that were dynamically requested from
elements with elementGetRequestPad
should be released with the
elementReleaseRequestPad
function instead.
Pads are not automatically deactivated so elements should perform the needed
steps to deactivate the pad in case this pad is removed in the PAUSED or
PLAYING state. See padSetActive
for more information about
deactivating pads.
The pad and the element should be unlocked when calling this function.
This function will emit the padRemoved
signal on the element.
Returns: True
if the pad could be removed. Can return False
if the
pad does not belong to the provided element.
:: ElementClass elementT | |
=> elementT |
|
-> IO (Iterator Pad) | an iterator over the element's pads. |
Retrieve an Iterator
over element
's pads.
elementIterateSinkPads :: ElementClass elementT => elementT -> IO (Iterator Pad)Source
Retrieve an Iterator
over element
's sink pads.
elementIterateSrcPads :: ElementClass elementT => elementT -> IO (Iterator Pad)Source
Retrieve an Iterator
over element
's src pads.
:: (ElementClass srcT, ElementClass sinkT) | |
=> srcT |
|
-> sinkT |
|
-> IO Bool |
Link src
to sink
. The link must be from source to
sink; the other direction will not be tried. The function
looks for existing pads that aren't linked yet. It will request
new pads if necessary. Such pads must be released manually (with
elementReleaseRequestPad
) when unlinking. If multiple links are
possible, only one is established.
Make sure you have added your elements to a Bin
or Pipeline
with binAdd
before trying to link them.
elementUnlink :: (ElementClass srcT, ElementClass sinkT) => srcT -> sinkT -> IO ()Source
Unlink all source pads of the src
from all sink pads of the
sink
.
:: (ElementClass srcT, ElementClass sinkT) | |
=> srcT |
|
-> Maybe String |
|
-> sinkT |
|
-> Maybe String |
|
-> IO Bool |
Link the named pads of src
and sink
.
:: (ElementClass srcT, ElementClass sinkT) | |
=> srcT |
|
-> String |
|
-> sinkT |
|
-> String |
|
-> IO () |
Unlink the named pads of src
and sink
.
:: (ElementClass srcT, ElementClass sinkT) | |
=> srcT |
|
-> Maybe String |
|
-> sinkT |
|
-> Maybe String |
|
-> Caps |
|
-> IO Bool |
:: (ElementClass srcT, ElementClass sinkT) | |
=> srcT |
|
-> sinkT |
|
-> Maybe Caps |
|
-> IO Bool |
Link src
to dest
using the given Caps
as a filter. The link
must be from source to sink; the other direction will not be
tried. The function looks for existing pads that aren't linked
yet. If will request new pads if necessary. If multiple links are
possible, only one is established.
Make sure you have added your elements to a Bin
or Pipeline
with binAdd
before trying to link them.
:: ElementClass elementT | |
=> elementT |
|
-> ClockTimeDiff |
|
-> IO () |
Set the base time of element
. See elementGetBaseTime
for more
information.
:: ElementClass elementT | |
=> elementT |
|
-> IO ClockTimeDiff | the base time of the element |
Return the base time of element
. The base time is the absolute
time of the clock when this element was last set to
StatePlaying
. Subtract the base time from the clock time to get
the stream time of the element.
:: (ElementClass elementT, BusClass busT) | |
=> elementT |
|
-> busT |
|
-> IO () |
Set the Bus
used by element
. For internal use only, unless
you're testing elements.
:: ElementClass elementT | |
=> elementT |
|
-> IO Bus | the bus used by the element |
Get the bus of element
. Not that only a Pipeline
will
provide a bus for the application.
:: ElementClass elementT | |
=> elementT |
|
-> IO ElementFactory | the factory that created |
Get the factory used to create element
.
:: (ElementClass elementT, IndexClass indexT) | |
=> elementT |
|
-> indexT |
|
-> IO () |
Set the Index
used by element
.
:: ElementClass elementT | |
=> elementT |
|
-> IO Bool |
|
Determine whether element
can be indexed.
:: ElementClass elementT | |
=> elementT |
|
-> IO Bool |
|
Determine whether element
requires a clock.
:: (ElementClass elementT, ClockClass clockT) | |
=> elementT |
|
-> clockT |
|
-> IO Bool |
|
Set the Clock
used by element
.
:: ElementClass elementT | |
=> elementT |
|
-> IO (Maybe Clock) | the clock, or |
Get the Clock
used by element
.
:: ElementClass elementT | |
=> elementT |
|
-> IO Bool |
|
Determine whether element
provides a clock. A Clock
provided
by an element can be used as the global clock for a pipeline. An
element that can provide a clock is only required to do so in the
StatePaused
state, meaning that it is fully negotiated and has
allocated the resources needed to operate the clock.
:: ElementClass elementT | |
=> elementT |
|
-> IO (Maybe Clock) |
Get the Clock
provided by element
.
Note that an element is only required to provide a clock in the
StatePaused
state. Some elements can provide a clock in other
states.
:: ElementClass elementT | |
=> elementT |
|
-> State |
|
-> IO StateChangeReturn | the result of the state change |
Set the state of element
to state
. This function will try to
set the requested state by going through all the intermediary
states and calling the class's state change function for each.
This function can return StateChangeAsync
, in which case the
element will perform the remainder of the state change
asynchronously in another thread. An application can use
elementGetState
to wait for the completion of the state change
or it can wait for a state change message on the bus.
:: ElementClass elementT | |
=> elementT |
|
-> ClockTime |
|
-> IO (StateChangeReturn, Maybe State, Maybe State) | the result of the state change, the current state, and the pending state |
Get the state of element
.
For elements that performed an asynchronous state change, as
reported by elementSetState
, this function will block up to the
specified timeout value for the state change to complete. If the
element completes the state change or goes into an error, this
function returns immediately with a return value of
StateChangeSuccess
or StateChangeFailure
, respectively.
This function returns StateChangeNoPreroll
if the element
successfully changed its state but is not able to provide data
yet. This mostly happens for live sources that not only produce
data in the StatePlaying
state. While the state change return
is equivalent to StateChangeSuccess
, it is returned to the
application to signal that some sink elements might not be able
to somplete their state change because an element is not
producing data to complete the preroll. When setting the element
to playing, the preroll will complete and playback will start.
:: ElementClass elementT | |
=> elementT |
|
-> Bool | |
-> IO Bool |
|
Lock the state of element
, so state changes in the parent don't
affect this element any longer.
:: ElementClass elementT | |
=> elementT |
|
-> IO Bool |
Determine whether element
's state is locked.
:: ElementClass elementT | |
=> elementT |
|
-> IO () |
Abort element
's state change. This function is used by elements
that do asynchronous state changes and find out something is wrong.
This function should be called with the state lock held.
Get a string representation of state
.
elementStateChangeReturnGetNameSource
:: StateChangeReturn |
|
-> String | the name of |
Get a string representation of stateRet
.
Since 0.10.11.
elementSyncStateWithParentSource
:: ElementClass elementT | |
=> elementT |
|
-> IO Bool |
|
Try to change the state of element
to the same as its
parent. If this function returns False
, the state of the
element is undefined.
elementGetQueryTypes :: ElementClass element => element -> IO [QueryType]Source
:: (ElementClass element, QueryClass query) | |
=> element |
|
-> query |
|
-> IO Bool |
|
Perform a query on the given element.
For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element.
:: ElementClass element | |
=> element |
|
-> Format |
|
-> Int64 |
|
-> Format |
|
-> IO (Maybe (Format, Word64)) | the resulting format and value |
Query an element for the convertion of a value from one format to another.
:: ElementClass element | |
=> element |
|
-> Format |
|
-> IO (Maybe (Format, Word64)) | the resulting format and value |
Query an element for its stream position.
:: ElementClass element | |
=> element |
|
-> Format |
|
-> IO (Maybe (Format, Word64)) | the resulting format and value |
Query an element for its stream duration.
:: (ElementClass element, EventClass event) | |
=> element |
|
-> event |
|
-> IO Bool |
|
Send an event to an element.
If the element doesn't implement an event handler, the event will be pushed to a random linked sink pad for upstream events or a random linked source pad for downstream events.
:: ElementClass element | |
=> element |
|
-> Format |
|
-> [SeekFlags] |
|
-> Int64 |
|
-> IO Bool |
|
Perform a seek on the given element. This function only supports
seeking to a position relative to the start of the stream. For
more complex operations like segment seeks (such as for looping),
or changing the playback rate, or seeking relative to the last
configured playback segment you should use elementSeek
.
In a completely prerolled pipeline in the StatePaused
or
StatePlaying
states, seeking is always guaranteed to return
True
on a seekable media type, or False
when the media type
is certainly not seekable (such as a live stream).
Some elements allow for seeking in the StateReady
state, in
which case they will store the seek event and execute it when
they are put into the StatePaused
state. If the element
supports seek in StateReady, it will always return True
when
it recieves the event in the StateReady
state.
:: ElementClass element | |
=> element |
|
-> Double |
|
-> Format |
|
-> [SeekFlags] |
|
-> SeekType |
|
-> Int64 |
|
-> SeekType |
|
-> Int64 |
|
-> IO Bool |
|
Send a seek event to an element. See
eventNewSeek
for the
details of the parameters. The seek event is sent to the element
using elementSendEvent
.
elementNoMorePads :: ElementClass element => Signal element (IO ())Source
The signal emitted when an element will not generate more dynamic pads.
elementPadAdded :: ElementClass element => Signal element (Pad -> IO ())Source
The signal emitted when a new Pad
has been added to the
element.
elementPadRemoved :: ElementClass element => Signal element (Pad -> IO ())Source
The signal emitted when a Pad
has been removed from the
element.