<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
> What are states?
</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Building a Filter"
HREF="part-building.html"><LINK
REL="PREVIOUS"
TITLE="The chain function"
HREF="chapter-building-chainfn.html"><LINK
REL="NEXT"
TITLE="Adding Arguments"
HREF="chapter-building-args.html"></HEAD
><BODY
CLASS="chapter"
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
> Plugin Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="chapter-building-chainfn.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-building-args.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-statemanage-states"
></A
>Chapter 6.
What are states?
</H1
><P
> A state describes whether the element instance is initialized, whether it
is ready to transfer data and whether it is currently handling data. There
are four states defined in <SPAN
CLASS="application"
>GStreamer</SPAN
>: <CODE
CLASS="classname"
>GST_STATE_NULL</CODE
>,
<CODE
CLASS="classname"
>GST_STATE_READY</CODE
>, <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
>
and <CODE
CLASS="classname"
>GST_STATE_PLAYING</CODE
>.
</P
><P
> <CODE
CLASS="classname"
>GST_STATE_NULL</CODE
> (from now on referred to as
<SPAN
CLASS="QUOTE"
>"NULL"</SPAN
>) is the default state of an element. In this state, it
has not allocated any runtime resources, it has not loaded any runtime
libraries and it can obviously not handle data.
</P
><P
> <CODE
CLASS="classname"
>GST_STATE_READY</CODE
> (from now on referred to as
<SPAN
CLASS="QUOTE"
>"READY"</SPAN
>) is the next state that an element can be in. In the
READY state, an element has all default resources (runtime-libraries,
runtime-memory) allocated. However, it has not yet allocated or defined
anything that is stream-specific. When going from NULL to READY state
(<CODE
CLASS="classname"
>GST_STATE_NULL_TO_READY</CODE
>), an element should
allocate any non-stream-specific resources and should load runtime-loadable
libraries (if any). When going the other way around (from READY to NULL,
<CODE
CLASS="classname"
>GST_STATE_READY_TO_NULL</CODE
>), an element should unload
these libraries and free all allocated resources. Examples of such
resources are hardware devices. Note that files are generally streams,
and these should thus be considered as stream-specific resources; therefore,
they should <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>not</I
></SPAN
> be allocated in this state.
</P
><P
> <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
> (from now on referred to as
<SPAN
CLASS="QUOTE"
>"PAUSED"</SPAN
>) is a state in which an element is by all means able
to handle data; the only 'but' here is that it doesn't actually handle
any data. When going from the READY state into the PAUSED state
(<CODE
CLASS="classname"
>GST_STATE_READY_TO_PAUSED</CODE
>), the element will
usually not do anything at all: all stream-specific info is generally
handled in the <CODE
CLASS="function"
>_link ()</CODE
>, which is called during caps
negotiation. Exceptions to this rule are, for example, files: these are
considered stream-specific data (since one file is one stream), and should
thus be opened in this state change. When going from the PAUSED back to
READY (<CODE
CLASS="classname"
>GST_STATE_PAUSED_TO_READY</CODE
>), all
stream-specific data should be discarded.
</P
><P
> <CODE
CLASS="classname"
>GST_STATE_PLAYING</CODE
> (from now on referred to as
<SPAN
CLASS="QUOTE"
>"PLAYING"</SPAN
>) is the highest state that an element can be in. It
is similar to PAUSED, except that now, data is actually passing over the
pipeline. The transition from PAUSED to PLAYING
(<CODE
CLASS="classname"
>GST_STATE_PAUSED_TO_PLAYING</CODE
>) should be as small
as possible and would ideally cause no delay at all. The same goes for the
reverse transition (<CODE
CLASS="classname"
>GST_STATE_PLAYING_TO_PAUSED</CODE
>).
</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-statemanage-filters"
>6.1. Mangaging filter state</A
></H1
><P
> An element can be notified of state changes through a virtual function
pointer. Inside this function, the element can initialize any sort of
specific data needed by the element, and it can optionally fail to
go from one state to another.
</P
><PRE
CLASS="programlisting"
> static GstElementStateReturn
gst_my_filter_change_state (GstElement *element);
static void
gst_my_filter_class_init (GstMyFilterClass *klass)
{
GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
element_class->change_state = gst_my_filter_change_state;
}
static GstElementStateReturn
gst_my_filter_change_state (GstElement *element)
{
GstMyFilter *filter = GST_MY_FILTER (element);
switch (GST_STATE_TRANSITION (element)) {
case GST_STATE_NULL_TO_READY:
if (!gst_my_filter_allocate_memory (filter))
return GST_STATE_FAILURE;
break;
case GST_STATE_READY_TO_NULL:
gst_my_filter_free_memory (filter);
break;
default:
break;
}
if (GST_ELEMENT_CLASS (parent_class)->change_state)
return GST_ELEMENT_CLASS (parent_class)->change_state (element);
return GST_STATE_SUCCESS;
}
</PRE
></DIV
></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="chapter-building-chainfn.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-building-args.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>The chain function</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-building.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Adding Arguments</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
