<!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 >