/usr/share/doc/gstreamer0.10-doc/pwg/html/chapter-other-base.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Pre-made base classes</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79;charset=UTF-8"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide (0.10.36)"
HREF="index.html"><LINK
REL="UP"
TITLE="Creating special element types"
HREF="part-other.html"><LINK
REL="PREVIOUS"
TITLE="Creating special element types"
HREF="part-other.html"><LINK
REL="NEXT"
TITLE="Writing a source"
HREF="section-base-src.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 (0.10.36)</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="part-other.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="section-base-src.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-other-base"
></A
>Chapter 19. Pre-made base classes</H1
><P
>&#13;    So far, we've been looking at low-level concepts of creating any type of
    <SPAN
CLASS="application"
>GStreamer</SPAN
> element. Now, let's assume that all you want is to create an
    simple audiosink that works exactly the same as, say,
    <SPAN
CLASS="QUOTE"
>"esdsink"</SPAN
>, or a filter that simply normalizes audio volume.
    Such elements are very general in concept and since they do nothing
    special, they should be easier to code than to provide your own scheduler
    activation functions and doing complex caps negotiation. For this purpose,
    <SPAN
CLASS="application"
>GStreamer</SPAN
> provides base classes that simplify some types of elements.
    Those base classes will be discussed in this chapter.
  </P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-base-sink"
>19.1. Writing a sink</A
></H1
><P
>&#13;      Sinks are special elements in <SPAN
CLASS="application"
>GStreamer</SPAN
>. This is because sink elements
      have to take care of <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>preroll</I
></SPAN
>, which is the process
      that takes care that elements going into the
      <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
> state will have buffers ready
      after the state change. The result of this is that such elements can
      start processing data immediately after going into the
      <CODE
CLASS="classname"
>GST_STATE_PLAYING</CODE
> state, without requiring to
      take some time to initialize outputs or set up decoders; all that is done
      already before the state-change to <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
>
      successfully completes.
    </P
><P
>&#13;      Preroll, however, is a complex process that would require the same
      code in many elements. Therefore, sink elements can derive from the
      <CODE
CLASS="classname"
>GstBaseSink</CODE
> base-class, which does preroll and
      a few other utility functions automatically. The derived class only
      needs to implement a bunch of virtual functions and will work
      automatically.
    </P
><P
>&#13;      The <CODE
CLASS="classname"
>GstBaseSink</CODE
> base-class specifies some
      limitations on elements, though:
    </P
><P
></P
><UL
><LI
><P
>&#13;          It requires that the sink only has one sinkpad. Sink elements that
          need more than one sinkpad, cannot use this base-class.
        </P
></LI
><LI
><P
>&#13;          The base-class owns the pad, and specifies caps negotiation, data
          handling, pad allocation and such functions. If you need more than
          the ones provided as virtual functions, then you cannot use this
          base-class.
        </P
></LI
><LI
><P
>&#13;          By implementing the <CODE
CLASS="function"
>pad_allocate ()</CODE
> function,
          it is possible for upstream elements to use special memory, such
          as memory on the X server side that only the sink can allocate, or
          even hardware memory <CODE
CLASS="function"
>mmap ()</CODE
>'ed from the kernel.
          Note that in almost all cases, you will want to subclass the
          <CODE
CLASS="classname"
>GstBuffer</CODE
> object, so that your own set of
          functions will be called when the buffer loses its last reference.
        </P
></LI
></UL
><P
>&#13;      Sink elements can derive from <CODE
CLASS="classname"
>GstBaseSink</CODE
> using
      the usual <CODE
CLASS="classname"
>GObject</CODE
> type creation voodoo, or by
      using the convenience macro <CODE
CLASS="function"
>GST_BOILERPLATE ()</CODE
>:
    </P
><PRE
CLASS="programlisting"
>&#13;GST_BOILERPLATE_FULL (GstMySink, gst_my_sink, GstBaseSink, GST_TYPE_BASE_SINK);

[..]

static void
gst_my_sink_class_init (GstMySinkClass * klass)
{
  klass-&#62;set_caps = [..];
  klass-&#62;render = [..];
[..]
}
    </PRE
><P
>&#13;      The advantages of deriving from <CODE
CLASS="classname"
>GstBaseSink</CODE
> are
      numerous:
    </P
><P
></P
><UL
><LI
><P
>&#13;          Derived implementations barely need to be aware of preroll, and do
          not need to know anything about the technical implementation
          requirements of preroll. The base-class does all the hard work.
        </P
><P
>&#13;          Less code to write in the derived class, shared code (and thus
          shared bugfixes).
        </P
></LI
></UL
><P
>&#13;      There are also specialized base classes for audio and video, let's look
      at those a bit.
    </P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-base-audiosink"
>19.1.1. Writing an audio sink</A
></H2
><P
>&#13;        Essentially, audio sink implementations are just a special case of a
        general sink. There are two audio base classes that you can choose to
        derive from, depending on your needs:
        <CODE
CLASS="classname"
>GstBaseAudiosink</CODE
> and
        <CODE
CLASS="classname"
>GstAudioSink</CODE
>. The baseaudiosink provides full
        control over how synchronization and scheduling is handled, by using
        a ringbuffer that the derived class controls and provides. The
        audiosink base-class is a derived class of the baseaudiosink,
        implementing a standard ringbuffer implementing default
        synchronization and providing a standard audio-sample clock. Derived
        classes of this base class merely need to provide a <CODE
CLASS="function"
>_open
        ()</CODE
>, <CODE
CLASS="function"
>_close ()</CODE
> and a <CODE
CLASS="function"
>_write
        ()</CODE
> function implementation, and some optional functions.
        This should suffice for many sound-server output elements and even
        most interfaces. More demanding audio systems, such as Jack, would
        want to implement the <CODE
CLASS="classname"
>GstBaseAudioSink</CODE
>
        base-class.
      </P
><P
>&#13;        The <CODE
CLASS="classname"
>GstBaseAusioSink</CODE
> has little to no
        limitations and should fit virtually every implementation, but is
        hard to implement. The <CODE
CLASS="classname"
>GstAudioSink</CODE
>, on the
        other hand, only fits those systems with a simple <CODE
CLASS="function"
>open
        ()</CODE
> / <CODE
CLASS="function"
>close ()</CODE
> / <CODE
CLASS="function"
>write
        ()</CODE
> API (which practically means pretty much all of them),
        but has the advantage that it is a lot easier to implement. The
        benefits of this second base class are large:
      </P
><P
></P
><UL
><LI
><P
>&#13;            Automatic synchronization, without any code in the derived class.
          </P
></LI
><LI
><P
>&#13;            Also automatically provides a clock, so that other sinks (e.g. in
            case of audio/video playback) are synchronized.
          </P
></LI
><LI
><P
>&#13;            Features can be added to all audiosinks by making a change in the
            base class, which makes maintenance easy.
          </P
></LI
><LI
><P
>&#13;            Derived classes require only three small functions, plus some
            <CODE
CLASS="classname"
>GObject</CODE
> boilerplate code.
          </P
></LI
></UL
><P
>&#13;        In addition to implementing the audio base-class virtual functions,
        derived classes can (should) also implement the
        <CODE
CLASS="classname"
>GstBaseSink</CODE
> <CODE
CLASS="function"
>set_caps ()</CODE
> and
        <CODE
CLASS="function"
>get_caps ()</CODE
> virtual functions for negotiation.
      </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="section-base-videosink"
>19.1.2. Writing a video sink</A
></H2
><P
>&#13;        Writing a videosink can be done using the
        <CODE
CLASS="classname"
>GstVideoSink</CODE
> base-class, which derives from
        <CODE
CLASS="classname"
>GstBaseSink</CODE
> internally. Currently, it does
        nothing yet but add another compile dependency, so derived classes
        will need to implement all base-sink virtual functions. When they do
        this correctly, this will have some positive effects on the end user
        experience with the videosink:
      </P
><P
></P
><UL
><LI
><P
>&#13;            Because of preroll (and the <CODE
CLASS="function"
>preroll ()</CODE
> virtual
            function), it is possible to display a video frame already when
            going into the <CODE
CLASS="classname"
>GST_STATE_PAUSED</CODE
> state.
          </P
></LI
><LI
><P
>&#13;            By adding new features to <CODE
CLASS="classname"
>GstVideoSink</CODE
>, it
            will be possible to add extensions to videosinks that affect all of
            them, but only need to be coded once, which is a huge maintenance
            benefit.
          </P
></LI
></UL
></DIV
></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="part-other.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="section-base-src.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Creating special element types</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-other.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Writing a source</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
gstreamer0.10-doc 0.10.36-1.5ubuntu1 / usr / share / doc / gstreamer0.10-doc / pwg / html / chapter-other-base.html
