<?xml version="1.0" encoding="UTF-8" ?>
<chapter id="libs3d">
<title>libs3d - The S3D API</title>
<sect1 id="using">
<title>Using the <application>s3d</application> library</title>
<sect2 id="setup">
<title>Setting <application>s3d</application> up</title>
 <para>
 Install the lib using the usual usual mechanism:
 <programlisting>
 cmake .
 make
 make install
 </programlisting>
 You might need to have superuser rights in order to do make install. You should now have the server,
 the library and some applications installed somewhere.
 </para>
</sect2>
<sect2 id="gettingstarted">
<title>Getting started</title>
<para>
 After having <application>s3d</application> installed, you can write your own <application>s3d</application> programs (yeah, that is what this guide is about ;)
 <programlisting>
 <![CDATA[#include <s3d.h>]]>
 </programlisting>
 should be enough to access the 3d functions. If you want to use keyboard interaction, do
 <programlisting>
 <![CDATA[#include <s3d_keysym.h>]]>
 </programlisting>
 for the keycode table.
 Now you can compile your program with 
 <screen>
 <prompt>bash$</prompt> <command> gcc <replaceable>program</replaceable>.c -ls3d -o <replaceable>program</replaceable> </command>
 That wasn't that hard, wasn't it?
 </screen>
</para>
</sect2>
</sect1>


<sect1 id="functions">
<title>function reference</title>

&libs3d_func;
</sect1>


<sect1 id="data_types">
<title>Data types</title>

&libs3d_struct;
&libs3d_typedef;
</sect1>




<sect1 id="definitions">
<title>Definitions</title>




<sect2 id="s3d_events">
<title>S3D events</title>
<para>
This defines the callback format. Each callback should return void and take an argument of <link linkend="structs3d_evt">struct s3d_evt *</link>.
Callbacks can be defined with <link linkend="s3d_set_callback">s3d_set_callback()</link>.
<variablelist>

<varlistentry>
<term><anchor id="S3D_EVENT_OBJ_CLICK"/>S3D_EVENT_OBJ_CLICK</term>
<listitem><para>
An object got clicked (when you set the flag <link linkend="S3D_OF_SELECTABLE">S3D_OF_SELECTABLE</link>), buf will contain the object id
of the object which got clicked (uint32_t)
</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_EVENT_KEY"/>S3D_EVENT_KEY</term>
<listitem><para>
A key was pressed, buf will contain a keycode. use  <![CDATA[#include <s3d_keysym.h>]]> to have the keycodes available. buf is a 2 byte unsigned short keycode.
</para></listitem>
</varlistentry>


<varlistentry>
<term><anchor id="S3D_EVENT_MBUTTON"/>S3D_EVENT_MBUTTON</term>
<listitem><para>
A mouse button was clicked. Use <link linkend="structs3d_but_info">struct s3d_but_info</link> on buf to get more info.
</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_EVENT_NEW_OBJECT"/>S3D_EVENT_NEW_OBJECT</term>
<listitem><para>
deprecated, will use <link linkend="S3D_EVENT_OBJ_INFO">S3D_EVENT_OBJ_INFO</link>
</para></listitem>
</varlistentry>


<varlistentry>
<term><anchor id="S3D_EVENT_OBJ_INFO"/>S3D_EVENT_OBJ_INFO</term>
<listitem><para>
Something happened to an object. This can happen if the camera was moved, the mouse (pointer) was moved or an application appeared/changed in the mcp

</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_MCP_OBJECT"/>S3D_MCP_OBJECT</term>
<listitem><para>
As the name suggests, those will only happen to the MCP. 
This tells it about new/changed application object. <link linkend="structmcp_object">struct mcp_object</link>
can be used on buf. To be removed in the future.
</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_MCP_DEL_OBJECT"/>S3D_MCP_DEL_OBJECT</term>
<listitem><para>
As the name suggests, those will only happen to the MCP. 
This tells it about deleted application object. <link linkend="structmcp_object">struct mcp_object</link>
can be used on buf. To be removed in the future.
</para></listitem>
</varlistentry>


<varlistentry>
<term><anchor id="S3D_EVENT_QUIT"/>S3D_EVENT_QUIT</term>
<listitem><para>
Server sent the quit signal, or the connection was terminated. Usually, this is only processed internally.
</para></listitem>
</varlistentry>



</variablelist>
</para>
<programlisting>
/* a callback handler could look like this: */
void my_key_handler(struct s3d_evt *event_data)
{
	...
}
</programlisting>
</sect2>


<sect2 id="s3d_object_flags">
<title>S3D Object Flags</title>
<para>
Objects can have several flags to change their behavior in the server and can be set with
<link linkend="s3d_flags_on">s3d_flags_on()</link> and
<link linkend="s3d_flags_off">s3d_flags_off()</link>
<variablelist>
<varlistentry>
<term><anchor id="S3D_OF_VISIBLE"/>S3D_OF_VISIBLE</term>
<listitem><para>default:off</para><para>
Obviously, if this flag is toggled the user can see it, if not it will be hidden. ;)
</para><para>
When an object is created it's turned off, so you will be able push your geometry data and
turn it on after you're done. That avoids flickering and stuff.
</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_OF_SELECTABLE"/>S3D_OF_SELECTABLE</term>
<listitem><para>default:off</para><para>
When this is toggled on, you will receive <link linkend="S3D_EVENT_OBJ_CLICK">click events</link>.
Don't use it if you don't need it, it will eat performance.
</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="S3D_OF_POINTABLE"/>S3D_OF_POINTABLE</term>
<listitem><para>default:off</para><para>
Placeholder for pointer (onmouseover-event enabler) events. Not implemented yet.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

</sect1>

<sect1 id="Notes">
<title>Additional Notes</title>
<sect2 id="alpha">
<title>About alpha transparency</title>
<para>
Alpha transparency works, but polygons don't get ordered in view direction on the server yet. So please don't
use this feature yet. If you have an easy idea how to do that with OpenGL please drop me a line.
</para>
</sect2>
</sect1>




</chapter>