259 lines
14 KiB
XML
259 lines
14 KiB
XML
|
<?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="blib-BModule-Internal-API">
|
||
|
|
<refmeta>
|
||
|
|
<refentrytitle>BModule Internal API</refentrytitle>
|
||
|
|
<manvolnum>3</manvolnum>
|
||
|
|
<refmiscinfo>BLIB Library</refmiscinfo>
|
||
|
|
</refmeta>
|
||
|
|
|
||
|
|
<refnamediv>
|
||
|
|
<refname>BModule Internal API</refname><refpurpose>the internal API for users of <link linkend="BModules">BModules</link></refpurpose>
|
||
|
|
</refnamediv>
|
||
|
|
|
||
|
|
<refsynopsisdiv><title>Synopsis</title>
|
||
|
|
|
||
|
|
<synopsis>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<link linkend="BModule">BModule</link>* <link linkend="b-module-new">b_module_new</link> (<link linkend="GType">GType</link> module_type,
|
||
|
|
<link linkend="gint">gint</link> width,
|
||
|
|
<link linkend="gint">gint</link> height,
|
||
|
|
<link linkend="guchar">guchar</link> *buffer,
|
||
|
|
<link linkend="BModulePaintCallback">BModulePaintCallback</link> paint_callback,
|
||
|
|
<link linkend="gpointer">gpointer</link> paint_data,
|
||
|
|
<link linkend="GError">GError</link> **error);
|
||
|
|
void <link linkend="b-module-set-aspect">b_module_set_aspect</link> (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="gdouble">gdouble</link> aspect_ratio);
|
||
|
|
<link linkend="gboolean">gboolean</link> <link linkend="b-module-prepare">b_module_prepare</link> (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="GError">GError</link> **error);
|
||
|
|
void <link linkend="b-module-relax">b_module_relax</link> (<link linkend="BModule">BModule</link> *module);
|
||
|
|
void <link linkend="b-module-start">b_module_start</link> (<link linkend="BModule">BModule</link> *module);
|
||
|
|
void <link linkend="b-module-stop">b_module_stop</link> (<link linkend="BModule">BModule</link> *module);
|
||
|
|
void <link linkend="b-module-event">b_module_event</link> (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="BModuleEvent">BModuleEvent</link> *event);
|
||
|
|
<link linkend="gint">gint</link> <link linkend="b-module-tick">b_module_tick</link> (<link linkend="BModule">BModule</link> *module);
|
||
|
|
void <link linkend="b-module-describe">b_module_describe</link> (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="gchar">gchar</link> **title,
|
||
|
|
<link linkend="gchar">gchar</link> **description,
|
||
|
|
<link linkend="gchar">gchar</link> **author);
|
||
|
|
</synopsis>
|
||
|
|
</refsynopsisdiv>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<refsect1>
|
||
|
|
<title>Description</title>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
<refsect1>
|
||
|
|
<title>Details</title>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-new"/>b_module_new ()</title>
|
||
|
|
<programlisting><link linkend="BModule">BModule</link>* b_module_new (<link linkend="GType">GType</link> module_type,
|
||
|
|
<link linkend="gint">gint</link> width,
|
||
|
|
<link linkend="gint">gint</link> height,
|
||
|
|
<link linkend="guchar">guchar</link> *buffer,
|
||
|
|
<link linkend="BModulePaintCallback">BModulePaintCallback</link> paint_callback,
|
||
|
|
<link linkend="gpointer">gpointer</link> paint_data,
|
||
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
||
|
|
<para>
|
||
|
|
This function tries to create the class for the <parameter>module_type</parameter> and
|
||
|
|
queries it with the given width and height. Only if the class can
|
||
|
|
handle the requested size, a <link linkend="BModule">BModule</link> instance is created and
|
||
|
|
initialized with the given values.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module_type</parameter> :</term>
|
||
|
|
<listitem><simpara> the type of module to create
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>width</parameter> :</term>
|
||
|
|
<listitem><simpara> width of the frame buffer
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>height</parameter> :</term>
|
||
|
|
<listitem><simpara> height of the frame buffer
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>buffer</parameter> :</term>
|
||
|
|
<listitem><simpara> pointer to a preallocated buffer or <literal>NULL</literal>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>paint_callback</parameter> :</term>
|
||
|
|
<listitem><simpara> the function to call in <link linkend="b-module-paint">b_module_paint</link>()
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>paint_data</parameter> :</term>
|
||
|
|
<listitem><simpara> data to pass to the <parameter>paint_callback</parameter>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
||
|
|
<listitem><simpara> location to store the error occuring, or <literal>NULL</literal> to ignore errors
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly allocate <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-set-aspect"/>b_module_set_aspect ()</title>
|
||
|
|
<programlisting>void b_module_set_aspect (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="gdouble">gdouble</link> aspect_ratio);</programlisting>
|
||
|
|
<para>
|
||
|
|
Sets the pixel (or window) aspect ratio for the <parameter>module</parameter>. Most
|
||
|
|
modules ignore this value but some may adapt their output to take
|
||
|
|
the shape of pixels into account.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>aspect_ratio</parameter> :</term>
|
||
|
|
<listitem><simpara> the new pixel aspect ratio (x / y)
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-prepare"/>b_module_prepare ()</title>
|
||
|
|
<programlisting><link linkend="gboolean">gboolean</link> b_module_prepare (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
||
|
|
<para>
|
||
|
|
This function first queries the module once more to check that it
|
||
|
|
can handle the current settings. If the query succeeds, the <link linkend="prepare">prepare</link>()
|
||
|
|
method of the module is called. The module should then prepare
|
||
|
|
itself and will be able to start as soon as <link linkend="b-module-start">b_module_start</link>() is called.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
||
|
|
<listitem><simpara> location to store the error occuring, or <literal>NULL</literal> to ignore errors
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> is the module has successfully prepared itself,
|
||
|
|
<literal>FALSE</literal> otherwise
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-relax"/>b_module_relax ()</title>
|
||
|
|
<programlisting>void b_module_relax (<link linkend="BModule">BModule</link> *module);</programlisting>
|
||
|
|
<para>
|
||
|
|
Calls the <link linkend="relax">relax</link>() method of the <parameter>module</parameter> causing it to release
|
||
|
|
resources allocated in <link linkend="b-module-prepare">b_module_prepare</link>().</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-start"/>b_module_start ()</title>
|
||
|
|
<programlisting>void b_module_start (<link linkend="BModule">BModule</link> *module);</programlisting>
|
||
|
|
<para>
|
||
|
|
Emits the start signal for <parameter>module</parameter>. If <parameter>module</parameter> has a lifetime set,
|
||
|
|
a timer is installed that stops the module when the lifetime expires.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
You need to prepare <parameter>module</parameter> by calling <link linkend="b-module-prepare">b_module_prepare</link>() before it
|
||
|
|
can be started.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-stop"/>b_module_stop ()</title>
|
||
|
|
<programlisting>void b_module_stop (<link linkend="BModule">BModule</link> *module);</programlisting>
|
||
|
|
<para>
|
||
|
|
Emits the stop signal for <parameter>module</parameter>. You may only call this function
|
||
|
|
for a <link linkend="BModule">BModule</link> that is currently running.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-event"/>b_module_event ()</title>
|
||
|
|
<programlisting>void b_module_event (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="BModuleEvent">BModuleEvent</link> *event);</programlisting>
|
||
|
|
<para>
|
||
|
|
Dispatches an event to <parameter>module</parameter> by calling its <link linkend="event">event</link>() method with
|
||
|
|
<parameter>event</parameter>. This function has no effect if the module is not currently
|
||
|
|
running.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>event</parameter> :</term>
|
||
|
|
<listitem><simpara> pointer to a <link linkend="BModuleEvent">BModuleEvent</link>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-tick"/>b_module_tick ()</title>
|
||
|
|
<programlisting><link linkend="gint">gint</link> b_module_tick (<link linkend="BModule">BModule</link> *module);</programlisting>
|
||
|
|
<para>
|
||
|
|
Calls the <link linkend="tick">tick</link>() method of <parameter>module</parameter>. You may only call this function
|
||
|
|
for a <link linkend="BModule">BModule</link> that is currently running.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of milliseconds until <link linkend="tick">tick</link>() should be
|
||
|
|
called again or -1 to indicate that no further ticks are requested
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
<refsect2>
|
||
|
|
<title><anchor id="b-module-describe"/>b_module_describe ()</title>
|
||
|
|
<programlisting>void b_module_describe (<link linkend="BModule">BModule</link> *module,
|
||
|
|
<link linkend="gchar">gchar</link> **title,
|
||
|
|
<link linkend="gchar">gchar</link> **description,
|
||
|
|
<link linkend="gchar">gchar</link> **author);</programlisting>
|
||
|
|
<para>
|
||
|
|
This function queries <parameter>module</parameter> for a title, description and the name
|
||
|
|
of the author. It does so by calling the modules <link linkend="describe">describe</link>() method.
|
||
|
|
You may pass <literal>NULL</literal> as return location if you are not interested in
|
||
|
|
a particular information. The <parameter>title</parameter> is guaranteed to be available,
|
||
|
|
<parameter>description</parameter> and <parameter>author</parameter> may be <literal>NULL</literal> if the module doesn't provide
|
||
|
|
this information.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
You must free all returned strings using <link linkend="g-free">g_free</link>() if you don't need
|
||
|
|
them any longer.</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para><variablelist role="params">
|
||
|
|
<varlistentry><term><parameter>module</parameter> :</term>
|
||
|
|
<listitem><simpara> a <link linkend="BModule">BModule</link> object
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>title</parameter> :</term>
|
||
|
|
<listitem><simpara> return location for the module title or <literal>NULL</literal>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>description</parameter> :</term>
|
||
|
|
<listitem><simpara> return location for the module description or <literal>NULL</literal>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
<varlistentry><term><parameter>author</parameter> :</term>
|
||
|
|
<listitem><simpara> return location for the name of the module author or <literal>NULL</literal>
|
||
|
|
</simpara></listitem></varlistentry>
|
||
|
|
</variablelist></refsect2>
|
||
|
|
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</refentry>
|