<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Element States</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79;charset=UTF-8"><LINK
REL="HOME"
TITLE="GStreamer Application Development Manual (0.10.36)"
HREF="index.html"><LINK
REL="UP"
TITLE="Elements"
HREF="chapter-elements.html"><LINK
REL="PREVIOUS"
TITLE="Linking elements"
HREF="section-elements-link.html"><LINK
REL="NEXT"
TITLE="Bins"
HREF="chapter-bins.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Application Development Manual (0.10.36)</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="section-elements-link.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 5. Elements</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-bins.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-elements-states"
>5.6. Element States</A
></H1
><P
> After being created, an element will not actually perform any actions
yet. You need to change elements state to make it do something.
<SPAN
CLASS="application"
>GStreamer</SPAN
> knows four element states, each with a very specific
meaning. Those four states are:
</P
><P
></P
><UL
><LI
><P
> <CODE
CLASS="classname"
>GST_STATE_NULL</CODE
>: this is the default state.
No resources are allocated in this state, so, transitioning to it
will free all resources. The element must be in this state when
its refcount reaches 0 and it is freed.
</P
></LI
><LI
><P
> <CODE
CLASS="classname"
>GST_STATE_READY</CODE
>: in the ready state, an
element has allocated all of its global resources, that is,
resources that can be kept within streams. You can think about
opening devices, allocating buffers and so on. However, the
stream is not opened in this state, so the stream positions is
automatically zero. If a stream was previously opened, it should
be closed in this state, and position, properties and such should
be reset.
</P
></LI
><LI
><P
> <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
>: in this state, an
element has opened the stream, but is not actively processing
it. An element is allowed to modify a stream's position, read
and process data and such to prepare for playback as soon as
state is changed to PLAYING, but it is <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>not</I
></SPAN
>
allowed to play the data which would make the clock run.
In summary, PAUSED is the same as PLAYING but without a running
clock.
</P
><P
> Elements going into the PAUSED state should prepare themselves
for moving over to the PLAYING state as soon as possible. Video
or audio outputs would, for example, wait for data to arrive and
queue it so they can play it right after the state change. Also,
video sinks can already play the first frame (since this does
not affect the clock yet). Autopluggers could use this same
state transition to already plug together a pipeline. Most other
elements, such as codecs or filters, do not need to explicitly
do anything in this state, however.
</P
></LI
><LI
><P
> <CODE
CLASS="classname"
>GST_STATE_PLAYING</CODE
>: in the PLAYING state,
an element does exactly the same as in the PAUSED state, except
that the clock now runs.
</P
></LI
></UL
><P
> You can change the state of an element using the function
<CODE
CLASS="function"
>gst_element_set_state ()</CODE
>. If you set an element
to another state, <SPAN
CLASS="application"
>GStreamer</SPAN
> will internally traverse all intermediate
states. So if you set an element from NULL to PLAYING, <SPAN
CLASS="application"
>GStreamer</SPAN
>
will internally set the element to READY and PAUSED in between.
</P
><P
> When moved to <CODE
CLASS="classname"
>GST_STATE_PLAYING</CODE
>, pipelines
will process data automatically. They do not need to be iterated in
any form. Internally, <SPAN
CLASS="application"
>GStreamer</SPAN
> will start threads that take this
task on to them. <SPAN
CLASS="application"
>GStreamer</SPAN
> will also take care of switching
messages from the pipeline's thread into the application's own
thread, by using a <A
HREF="http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBus.html"
TARGET="_top"
><CODE
CLASS="classname"
>GstBus</CODE
></A
>. See
<A
HREF="chapter-bus.html"
>Chapter 7</A
> for details.
</P
><P
> When you set a bin or pipeline to a certain target state, it will usually
propagate the state change to all elements within the bin or pipeline
automatically, so it's usually only necessary to set the state of the
top-level pipeline to start up the pipeline or shut it down. However,
when adding elements dynamically to an already-running pipeline, e.g.
from within a "pad-added" or "new-decoded-pad" signal callback, you
need to set it to the desired target state yourself using
<CODE
CLASS="function"
>gst_element_set_state ()</CODE
> or
<CODE
CLASS="function"
>gst_element_sync_state_with_parent ()</CODE
>.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="section-elements-link.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="chapter-bins.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Linking elements</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="chapter-elements.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Bins</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
