swfdecbuffer.xml

Swfdec is a decoder/renderer for Macromedia Flash animations. The decoding and rendering engine is

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="swfdec-SwfdecBuffer">
<refmeta>
<refentrytitle role="top_of_page">SwfdecBuffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>SWFDEC Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>SwfdecBuffer</refname>
<refpurpose>memory region handling</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



                    <link linkend="SwfdecBuffer">SwfdecBuffer</link>;
                    <link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link>;
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new">swfdec_buffer_new</link>                   (void);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new-and-alloc">swfdec_buffer_new_and_alloc</link>         (<link linkend="guint">guint</link> size);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new-and-alloc0">swfdec_buffer_new_and_alloc0</link>        (<link linkend="guint">guint</link> size);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new-for-data">swfdec_buffer_new_for_data</link>          (unsigned <link linkend="char">char</link> *data,
                                                         <link linkend="guint">guint</link> size);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new-subbuffer">swfdec_buffer_new_subbuffer</link>         (<link linkend="SwfdecBuffer">SwfdecBuffer</link> *buffer,
                                                         <link linkend="guint">guint</link> offset,
                                                         <link linkend="guint">guint</link> length);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-new-from-file">swfdec_buffer_new_from_file</link>         (const <link linkend="char">char</link> *filename,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-ref">swfdec_buffer_ref</link>                   (<link linkend="SwfdecBuffer">SwfdecBuffer</link> *buffer);
<link linkend="void">void</link>                <link linkend="swfdec-buffer-unref">swfdec_buffer_unref</link>                 (<link linkend="SwfdecBuffer">SwfdecBuffer</link> *buffer);
<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link>*  <link linkend="swfdec-buffer-queue-new">swfdec_buffer_queue_new</link>             (void);
<link linkend="void">void</link>                <link linkend="swfdec-buffer-queue-clear">swfdec_buffer_queue_clear</link>           (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link>*  <link linkend="swfdec-buffer-queue-ref">swfdec_buffer_queue_ref</link>             (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="swfdec-buffer-queue-unref">swfdec_buffer_queue_unref</link>           (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="guint">guint</link>               <link linkend="swfdec-buffer-queue-get-depth">swfdec_buffer_queue_get_depth</link>       (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="guint">guint</link>               <link linkend="swfdec-buffer-queue-get-offset">swfdec_buffer_queue_get_offset</link>      (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="swfdec-buffer-queue-push">swfdec_buffer_queue_push</link>            (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue,
                                                         <link linkend="SwfdecBuffer">SwfdecBuffer</link> *buffer);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-queue-pull">swfdec_buffer_queue_pull</link>            (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue,
                                                         <link linkend="guint">guint</link> length);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-queue-pull-buffer">swfdec_buffer_queue_pull_buffer</link>     (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue);
<link linkend="SwfdecBuffer">SwfdecBuffer</link>*       <link linkend="swfdec-buffer-queue-peek">swfdec_buffer_queue_peek</link>            (<link linkend="SwfdecBufferQueue">SwfdecBufferQueue</link> *queue,
                                                         <link linkend="guint">guint</link> length);

</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
This section describes how memory is to be handled when interacting with the 
Swfdec library. Memory regions are refcounted and passed using a 
<link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link>. If large memory segments need to be handled that may span
multiple buffers, Swfdec uses a <link linkend="SwfdecBufferQueue"><type>SwfdecBufferQueue</type></link>.</para>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="SwfdecBuffer" role="struct"/>SwfdecBuffer</title>
<indexterm><primary>SwfdecBuffer</primary></indexterm><programlisting>typedef struct {
  unsigned char *data;
  guint length;
} SwfdecBuffer;
</programlisting>
<para>
To allow for easy sharing of memory regions, <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> was created. 
Every buffer refers to a memory region and its size and takes care of 
freeing that region when the buffer is no longer needed. They are 
reference countedto make it easy to refer to the same region from various
independant parts of your code. Buffers also support some advanced 
functionalities like extracting parts of the buffer using 
<link linkend="swfdec-buffer-new-subbuffer"><function>swfdec_buffer_new_subbuffer()</function></link> or using mmapped files with 
<link linkend="swfdec-buffer-new-from-file"><function>swfdec_buffer_new_from_file()</function></link> without the need for a different API.</para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term>unsigned&nbsp;<link linkend="char">char</link>&nbsp;*<structfield>data</structfield>;</term>
<listitem><simpara> the data. read-only
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="guint">guint</link>&nbsp;<structfield>length</structfield>;</term>
<listitem><simpara> number of bytes in <parameter>data</parameter>. read-only
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SwfdecBufferQueue" role="struct"/>SwfdecBufferQueue</title>
<indexterm><primary>SwfdecBufferQueue</primary></indexterm><programlisting>typedef struct {
} SwfdecBufferQueue;
</programlisting>
<para>
A <link linkend="SwfdecBufferQueue"><type>SwfdecBufferQueue</type></link> is a queue of continuous buffers that allows reading
its data in chunks of pre-defined sizes. It is used to transform a data 
stream that was provided by buffers of random sizes to buffers of the right
size.</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new" role="function"/>swfdec_buffer_new ()</title>
<indexterm><primary>swfdec_buffer_new</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new                   (void);</programlisting>
<para>
Creates a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> to be filled by the user. Use like this:
<informalexample><programlisting>SwfdecBuffer *buffer = swfdec_buffer_new ();
buffer->data = mydata;
buffer->length = mydata_length;
buffer->free = mydata_freefunc;</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> referencing nothing.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new-and-alloc" role="function"/>swfdec_buffer_new_and_alloc ()</title>
<indexterm><primary>swfdec_buffer_new_and_alloc</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new_and_alloc         (<link linkend="guint">guint</link> size);</programlisting>
<para>
Creates a new buffer and allocates new memory of <parameter>size</parameter> bytes to be used with 
the buffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> amount of bytes to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> with buffer->data pointing to new data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new-and-alloc0" role="function"/>swfdec_buffer_new_and_alloc0 ()</title>
<indexterm><primary>swfdec_buffer_new_and_alloc0</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new_and_alloc0        (<link linkend="guint">guint</link> size);</programlisting>
<para>
Createsa new buffer just like <link linkend="swfdec-buffer-new-and-alloc"><function>swfdec_buffer_new_and_alloc()</function></link>, but ensures 
that the returned data gets initialized to be 0.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> amount of bytes to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> with buffer->data pointing to new data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new-for-data" role="function"/>swfdec_buffer_new_for_data ()</title>
<indexterm><primary>swfdec_buffer_new_for_data</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new_for_data          (unsigned <link linkend="char">char</link> *data,
                                                         <link linkend="guint">guint</link> size);</programlisting>
<para>
Takes ownership of <parameter>data</parameter> and creates a new buffer managing it.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> memory region allocated with <link linkend="g-malloc"><function>g_malloc()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> size of <parameter>data</parameter> in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> pointing to <parameter>data</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new-subbuffer" role="function"/>swfdec_buffer_new_subbuffer ()</title>
<indexterm><primary>swfdec_buffer_new_subbuffer</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new_subbuffer         (<link linkend="SwfdecBuffer">SwfdecBuffer</link> *buffer,
                                                         <link linkend="guint">guint</link> offset,
                                                         <link linkend="guint">guint</link> length);</programlisting>
<para>
Creates a <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> for managing a partial section of the memory pointed
to by <parameter>buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> managing the region of memory
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&nbsp;:</term>
<listitem><simpara> starting offset into data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> amount of bytes to manage
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="SwfdecBuffer"><type>SwfdecBuffer</type></link> managing the indicated region.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-buffer-new-from-file" role="function"/>swfdec_buffer_new_from_file ()</title>
<indexterm><primary>swfdec_buffer_new_from_file</primary></indexterm><programlisting><link linkend="SwfdecBuffer">SwfdecBuffer</link>*       swfdec_buffer_new_from_file         (const <link linkend="char">char</link> *filename,
                                                         <link linkend="GError">GError</link> **error);</programlisting>