spec.docbook

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"/usr/share/sgml/docbook/xml-dtd-4.3/docbookx.dtd" [
 <!ENTITY Bez           "B&eacute;zier">

 <!ENTITY Types         SYSTEM "protocol/types.snip">
 <!ENTITY Commands      SYSTEM "protocol/cmd.snip">
 <!ENTITY Command-Index SYSTEM "protocol/cmd-indx.snip">
 <!ENTITY API           SYSTEM "protocol/api.snip">
 <!ENTITY GNUFDL        SYSTEM "fdl.xml">
 <!ENTITY time_s	"<varname>time_s</varname>">
 <!ENTITY time_f	"<varname>time_f</varname>">
]>

<book lang="en">

<bookinfo>
 <title>The Verse Specification</title>
 <subtitle>A platform for sharing 3D data</subtitle>
 <author><firstname>Emil</firstname>  <surname>Brink</surname></author>
 <author><firstname>Eskil</firstname> <surname>Steenberg</surname></author>
 <copyright><year>2004-2007</year><holder>PDC, KTH</holder></copyright>

 <!-- We mis-use the abstract (apologies) mildly, to contain the version symbol. -->
 <abstract>
  <para>
   This document describes version R6 of the Verse platform. The description
   covers the data model, the protocol, and the client API.
  </para>
 </abstract>

 <!-- For reasons unknown, this log isn't actually rendered in the final HTML. -->
 <revhistory>
  <revision>
   <revnumber>R6-2</revnumber>
   <date>February, 2007</date>
   <authorinitials>eb</authorinitials>
   <revremark>Added lots of text in the Security section</revremark>
  </revision>
  <revision>
   <revnumber>R6</revnumber>
   <date>June 2006</date>
   <authorinitials>eb</authorinitials>
   <revremark>Updated for Verse R6 release.</revremark>
  </revision>
 </revhistory>

 <legalnotice>
  <para>
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.2
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled
   <link linkend='gfdl'>GNU Free Documentation License</link>.
  </para>
 </legalnotice>
</bookinfo>

<preface id='preface'>
<title>Preface</title>
<abstract>
<title>Abstract</title>
<para>This is the Official Verse Specification. It is intended to fully specify the Verse platform,
by breaking it down into manageable parts and then describing each of those in an exhaustive manner.
</para>
<para>
This specification should be complete and precise enough to serve as the basis for creating a
new Verse implementation, while retaining compatibility on all levels with the existing one.
</para>
<para>
While great care has been taken in preparing this document, there will most likely be omissions
or even errors. We apologize, and ask that you help us improve this document whenever you find
a problem, by reporting it to us. Thanks.
</para>
</abstract>
</preface>

<chapter id='introduction'>
<title>Introduction</title>
<para>
</para>
<sect1>
<title>What is Verse?</title>
<para>
Verse is a platform for building networked applications centered around sharing and processing 3D data.
It consists of three parts, on different levels of abstraction:
the <link linkend="datamodel">data model</link>,
the <link linkend="protocol">network protocol</link>, and
the <link linkend="api">programming interface</link>. Below are condensed descriptions of these
three parts, hoping to convey a general idea quickly.
<variablelist>
<varlistentry>
<term><link linkend="datamodel">Data Model</link></term>
<listitem>
<para>
Verse defines a data model, which in turn defines exactly how data is formatted and stored.
The model is optimized and tailored for handling data suitable for building very dynamic
and highly interactive virtual worlds.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><link linkend="protocol">Network Protocol</link></term>
<listitem>
<para>
In order to make the data model accessible remotely, Verse defines a set of commands that can
be used to interact with data hosted on some computer. This set of commands is encoded on the
network in the exact manner described by the network protocol specification.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><link linkend="api">Programming Interface</link></term>
<listitem>
<para>
To make creating applications that use the Verse data model and protocol easy, a reference
application programming interface (<acronym>API</acronym>) has been created.
</para>
</listitem>
</varlistentry>
</variablelist>
The sections linked by the terms above provide plenty of additional detail about these three
parts of the platform, and appear in the order recommended for reading them.
</para>
</sect1>

<sect1 id='about'>
<title>About this Document</title>
<para>
This document is intended to be a complete specification of the Verse system, in all its parts. It begins
by describing the data model, moves along to how the data model is made available over a network, and finally
talks about the Verse standard C application programming interface.
</para>
<para>
The reader is assumed to have a certain level of technical proficiency, since this document often has reason
to be rather low-level. The detail level can be said to increase over the three major parts, but this is more
of a general trend than a struct rule.
</para>
<para>
This document was written by Emil Brink, with much of the initial structure and text coming from an original document
by Eskil Steenberg, and his reference implementation of the Verse standard. Most of the document was written in the
<ulink url='http://www.docbook.org/'>DocBook</ulink> format, although much of the highly structured data
(the type, command and API references) were created programmatically from custom XML data, processed into
DocBook using <ulink url='http://www.w3.org/TR/xslt'>XSLT</ulink>.
</para>
</sect1>

</chapter>

<chapter id="datamodel">
<title>Data Model</title>
<para>
One core part of Verse is a data model for storing 3D data detailed enough to describe a <quote>virtual world</quote>.
The data model tries hard to allow for as much flexibility as possible in what can be stored, while also trying
to be no larger than necessary. This section will describe this data model exhaustively, by presenting the the
abstractions and structures used to represent data throughout Verse. We begin with the underlying idea, the
almost-philosophical concept of perfect data.
</para>
<note>
<para>
Throughout this section, sidebars labelled <quote>API Link</quote> appear, that reference you straight to the
function(s) in the <link linkend='api'>API chapter</link> that deal with that particular aspect of the model.
</para>
</note>

<!-- DO NOT MENTION NODES YET! -->
<sect1>
<title>Perfect Data</title>
<para>
Verse's data model is designed around the philosophy of "perfect data". With this, it is meant that the data
doesn't describe <emphasis>how</emphasis> to render the graphics, but more how the graphics should look.
It is then up to each client to do a "best effort render" of the data. The idea is to support creation of
datasets that are as easy as possible to use independently of the application.
</para>
<para>
The 3D geometry data is based around a single primitive: subdivided polygons. A subdivided polygon is
an ordinary polygon that has been extended with information about its <emphasis>creases</emphasis>,
allowing subdivision algorithms to intelligently split the single polygon into several to create a
3:rd degree curved surface that is smooth. This means that you may display the graphics as
simple, planar, polygons, but you can also subdivide them to increase the smoothness of the surfaces.
Subdivision is compatible with a lot of existing 3D software, since you can convert polygons, B-splines,
patches and NURBS into subdivision surfaces without loss of precision.
</para>
<para>
The Verse data model has many features such as:
<itemizedlist>
<listitem><para>An advanced shader tree supporting surface properties like
color, texture, lighting and displacement.</para></listitem>
<listitem><para>High dynamic range textures.</para></listitem>
<listitem><para>Animation curves.</para></listitem>
<listitem><para>Generic surface properties for storing UV, color, selections and other data.</para></listitem>
<listitem><para>A system-wide <emphasis>tag system</emphasis> lets users store additional custom data.</para></listitem>
</itemizedlist>
</para>
<para>
Verse can store text that lets each object be associated with scripts; these scripts can be read and executed by a
client, which can run on the server side. This is a very flexible way of doing scripting, since engines
can be written by anyone and for any language, making Verse language-independent. In addition to the text node
and tags, object nodes can have generic method calls that can be passed between clients.
</para>
</sect1>

<sect1 id='sessions'>
<title>Sessions</title>
<para>
At the top level, Verse data is always associated with with a <emphasis>session</emphasis>. Session is a name for
the connection between two applications that talk using the Verse protocol. Typically, in such a situation, one
end is called the <emphasis>host</emphasis> and the other is the <emphasis>client</emphasis>.
</para>
<para>
Hosts are mainly passive, acting as containers of data made available to clients. Clients do all the work by
connecting to a host and manipulating (reading, writing, creating, editing, and generally using) the data held
by it. Several clients can connect to the same host simultaneously, and will then be given individual views of
the data contained on the server. Typically, much data will be shared, so that they both get the sensation of
being in the same world and so that data modified by one client is visible to all other clients.
</para>
<para>
At the user level, hosts are perceived as <quote>containing</quote> a world, and making it available to clients
through the Verse protocol. In this regard, Verse hosts are very similar to the server in any common client-server
system, such as a web server for instance. It stores content, and makes it available to clients through a well-defined
communications protocol.
</para>
<sect2>
<title>Time</title>
<para>
Many operations in Verse are independent of time, they happen <emphasis>now</emphasis>, which is as soon as
the data arrives, it is assumed to be valid immediately upon receipt. Some operations, however, do not make
sense without a concept of time. As we'll see later, it is possible for a client to read out the current time,
and receive a value which is (more or less) in sync with the host's idea of what time it is.
</para>
<para>
Time is counted in seconds, with a precision of 64 bits. Of these, 32 bits are the number of whole seconds since
some unspecified previous event (such as the starting of the host), while the remaining 32 bits are fractions.
Fractions are used so that times less than one second can be expressed. So, time is a pair of unsigned 32-bit integers,
one called &time_s; (the whole seconds) and the other &time_f; (the fractional part).
</para>
<para>
The &time_f; fractional part is in units of 1/4,294,967,296:th of a second. This means that the time
<quote>four and a half seconds</quote> is expressed as the pair of values (&time_s;=4, &time_f;=2,147,483,648).
</para>
</sect2>
</sect1>

<sect1 id="subscription">
<title>Subscription</title>
<para>
In order for the client side to be able to participate in the session created by connecting to a host, it must
ask the host for data. This is done by <emphasis>subscribing</emphasis> to data of interest. Only clients are
allowed to subscribe to data, and hosts are only allowed to send data to a client that has been explicitly
requested in the form of a subscription.
</para>
<para>
When a client first subscribes to some piece of data, such as a polygon mesh, the host must send the current
state of that data to the client. Then, whenever the data changes, it must send those changes to the client
for as long as the client remains a subscriber. From the client's point of view, there is no difference in
handling initial data being sent, and handling changes later on: they are all delivered in the same way which
makes it easy to deal data in this fashion.
</para>
<para>
<emphasis>All</emphasis> data made available by a Verse host can be accessed through subscription in one way
or another, and being a subscriber is generally required before data can be read or written easily. This is
because being a subcriber ensures that the client has full access to whatever addressing information is used
for the data in question.
</para>
<note>
<para>
It is not the intent of the subscription system to serve as a security device, to
limit access to data to those clients that are subscribed. For instance, it is perfectly legal to create a
new <link linkend='n-geometry'>geometry node</link>, and then immediately send vertex and polygon data to the
known layers <literal>0</literal> and <literal>1</literal>. Because these layers are known to exist in all
geometry nodes, it is not even necessary to subscribe to the <emphasis>node</emphasis>, much less the layers.
</para>
<para>
The main purpose of the subscription-oriented data access architecture is to limit the bandwidth used by a
client, by permitting a client to tell a host which data it is interested in, and thus which data it needs
to download and receive updates to.
</para>
</note>
<para>
There is no data that cannot be changed at any time during a session, which helps make the system very dynamic.
Being prepared for this and designing data structures accordingly is a great skill to have when writing Verse
applications.
</para>
</sect1>

<sect1 id="nodes">
<title>Nodes</title>
<para>
All data in Verse is arranged into <emphasis>nodes</emphasis>. Nodes group data according to
it's character, and are optimized for storing one particular kind of data per node type. There
are seven distinct node types defined: Object, Geometry, Material, Bitmap, Text, Audio and Curve.
</para>
<para>
Nodes are identified <emphasis>within a session</emphasis> through numbers assigned by the host. All node IDs
are valid only inside that session; two clients running on the same physical machine but connected to the same
host cannot directly exchange node IDs with each other and expect a sensible result. See below for a portable
way to reference nodes, however.
</para>
<para>
As we shall see, most nodes have a lot of internal structure (layers, fragments, buffers, channels, et cetera), that
are always also identified using numerical IDs. Unlike node IDs, these numbers <emphasis>can</emphasis> be shared
as long as the context is also provided. So, if a host contains a geometry node that client A knows as node
number 4096, and client B knows as node number 8999, the layer that A thinks is 4096.17 will be the exact same
data as B sees as 8999.17. This is harder to explain in a simple way, than it is to actually understand, we hope.
</para>

<sect2>
<title>Common Data</title>
<para>
There are some data storage facilities shared by all nodes, regardless of the node's type. These are described
below.
</para>
<sect3>
<title>Name</title>
<para>
All nodes have, in addition to the numerical ID mentioned above, a textual name. Unlike the IDs, the names are
<emphasis>not</emphasis> session-specific but can be shared between sessions. Names should be unique across
all nodes.
</para>
<sidebar>
<title>API Link</title>
<para>To set the name of a node, use the <xref linkend='verse_send_node_name_set'/> function.
</para>
</sidebar>
</sect3>
<sect3>
<title>Tags</title>
<para>
<emphasis>Tags</emphasis> provide a place where applications can store custom data associated with a node. This
is handy for expressing things that do not fit straight into the data model, but are nevertheless required by
applications for processing. Tags are like variables in a programming language; they have a name (and a numerical
ID for reference, as always) and a value of a certain type. There are numerical and textual types, plus some more
intricate ones.
</para>
<para>
To ease management, tags are collected into <emphasis>tag groups</emphasis>. Tag groups are simply named containers
for tags, that allow related tags to be grouped together. Also, tag groups can be subscribed to which gives better
subscription granularity than if individual tags could be. Tag groups do not nest, it is not possible to have
groups within groups within groups.
</para>
<para>
These are the types of tag values supported:
<informaltable>
<tgroup cols='2'>
<thead>
 <row>
  <entry align='center'>Name</entry>
  <entry align='left'>Description</entry>
 </row>
</thead>
<tbody>
 <row>
  <entry>VN_TAG_BOOLEAN</entry>
  <entry>Boolean value, i.e. true or false only.</entry>
 </row>
 <row>
  <entry>VN_TAG_UINT32</entry>
  <entry>Unsigned 32-bit integer value.</entry>
 </row>
 <row>
  <entry>VN_TAG_REAL64</entry>
  <entry>64-bit floating point value.</entry>
 </row>
 <row>
  <entry>VN_TAG_STRING</entry>
  <entry>A textual string.</entry>
 </row>
 <row>
  <entry>VN_TAG_REAL64_VEC3</entry>
  <entry>Vector of three 64-bit floating point values.</entry>
 </row>
 <row>
  <entry>VN_TAG_LINK</entry>
  <entry>Link to another node.</entry>
 </row>
 <row>
  <entry>VN_TAG_ANIMATION</entry>
  <entry>Link to a <link linkend='n-curve'>curve node</link>. Subject to change.</entry>
 </row>
 <row>
  <entry>VN_TAG_BLOB</entry>
  <entry>Unstructured binary data (<quote>binary large object</quote>).</entry>
 </row>
</tbody>
</tgroup>
</informaltable>
A tag always has a value, which means that it always has exactly one type. It is possible to rename, delete,
and change the type of tags, as well as create new tags of course. We will see later on how these actions
are performed, in the <link linkend='system-commands'>system commands</link> section.
</para>
<sidebar>
<title>API Links</title>
<para>Tags groups are manipulated using the <xref linkend='verse_send_tag_group_create'/>,
<xref linkend='verse_send_tag_group_destroy'/>,
<xref linkend='verse_send_tag_group_subscribe'/> and
<xref linkend='verse_send_tag_group_unsubscribe'/> functions. Tags are manipulated using the
<xref linkend='verse_send_tag_create'/> and <xref linkend='verse_send_tag_destroy'/> functions.
</para>
</sidebar>
</sect3>
</sect2>

</sect1>

<sect1 id="n-object" xreflabel='object node'>
<title>The Object Node</title>
<para>
The <emphasis>object node</emphasis> acts as the root for data storage in Verse's data model. Its purpose is to
represent <quote>objects</quote> in a virtual world. All data in nodes of other types goes unused unless it is connected
to a tree rooted in an object node. The object node itself does not hold much actual data, but it provides
a transform and various other features.
</para>

<sect2 id='obj-link'>
<title>Links</title>
<para>
The object node has the ability to link to other nodes, specifying different properties (geometry, materials,
associated scripts and so son) of the represented object. Multiple object nodes may all link to the same geometry
node, to share the data and thus create several identical copies of an object.
</para>
<para>
Links are unidirectional, going <emphasis>from</emphasis> an object node and <emphasis>to</emphasis> the link
target which can be a node of any type. Links have textual labels, which are used to denote the purpose of
the link (for instance, the main geometry link from an object node to a geometry node is labelled
<quote><literal>geometry</literal></quote>). Link labels need not be unique; there can be several links sharing a
single label. There is also an integer field in the link definition, called target. This field is used to refer to some
part of the source or destination node.
</para>
<para>
These are the currently defined standard link labels, with their use:
</para>
<variablelist>
<varlistentry>
<term><literal>child</literal></term>
<listitem>
<para>
Links to a child object, that resides in the parent node's coordinate space. This is used to define hierarchical
transform graphs. The <literal>target</literal> should be set to the numerical ID of the <link linkend='geometry-bones'>bone</link>
to which the child is to be attached, or the special value ~0 (<literal>4,294,967,295</literal>) to indicate that the child
resides at the root of the parent's transform. It is valid to link to the same object from several different parent
objects. Transform hierarchies, however, cannot include circular links (a node cannot be its own child, at any level).
It is not guaranteed that a Verse host will not send out circular links, however. Clients need to be careful when
parsing the child link data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>geometry</literal></term>
<listitem>
<para>
The object's geometry. The referenced node, which should really be a <link linkend='n-geometry'>geometry node</link>,
defines the object's geometry in the world. The geometry will be translated to the object's position, rotated,
scaled, and also given any defined material. This link type does not use the <literal>target</literal> field.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>light</literal></term>
<listitem>
<para>
This specifies how light is emitted by the object. The referenced node should be a <link linkend='n-geometry'>geometry node</link>,
and it defines the shape of the light source. Each polygon of the geometry is taken to be an area light. At the time of writing,
no known renderer supports light links.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>material</literal></term>
<listitem>
<para>
The object's material. The referenced node, which should really be a <link linkend='n-material'>material node</link>,
defines the material to apply to the surface of the object during rendering. There can be more than one such link,
for objects that need more than one material. They are then all given the label <literal>material</literal>, and
assigned unique <literal>target</literal> values. A face integer layer named <literal>material</literal> is then added
to the geometry, and populated with integers from the set of <literal>target</literal> values to pick one of the available
materials for each of the faces.
</para>
</listitem>
</varlistentry>
</variablelist>
<sidebar>
<title>API Link</title>
<para>Object links are set using the <xref linkend='verse_send_o_link_set'/> function.</para>
</sidebar>
</sect2>

<sect2 id='obj-transform'>
<title>Transform</title>
<para>
The object node holds a full 3D transform, with translation, rotation and scaling components that are used
to orient the object in the world. The first two of these properties are modeled not only with absolute values,
but also with time derivatives i.e. speed and acceleration. There is also support for expressing <emphasis>drag</emphasis>,
allowing basic friction to be modeled.
</para>
<para>
For each of these properties, the value is calculated by a 3D vector equation like the following:
<informalequation>
<alt>p(t) = p0 + v0*t + a*t^2 / 2 + drag</alt>
<graphic fileref='media/object/transform-eq.png'/>
</informalequation>
Here, the symbol <varname>p</varname> is used to represent the transform property of interest,
<varname>p0</varname> is the last known absolute position, <varname>v0</varname> the set initial speed,
<varname>a</varname> the acceleration, and <varname>drag</varname> a friction term. The position is
a function of the time, <varname>t</varname>, and thus it is possible to extrapolate into the future
from the last known values of the various parameters. The equation is the same for both position and
rotation of an object. Verse does not currently provide support for extrapolating the scale part of
an object's transform.
</para>
<para>
Hosts will maintain values of an object's transform using fairly high numerical precision, but it is
possible for a client to request a lower precision to conserve bandwidth.
</para>
<para>
The object node is the <emphasis>only</emphasis> node to provide a transform. Other types of data
that need to be associated to a point in space need to do so by being linked from an object node
at the required position.
</para>
<sidebar>
<title>API Links</title>
<para>Object transform is set using the
<xref linkend='verse_send_o_transform_pos_real32'/>,
<xref linkend='verse_send_o_transform_pos_real64'/>,
<xref linkend='verse_send_o_transform_rot_real32'/>,
<xref linkend='verse_send_o_transform_rot_real64'/>,
<xref linkend='verse_send_o_transform_rot_real32'/> and
<xref linkend='verse_send_o_transform_rot_real64'/>
 functions.</para>
</sidebar>
</sect2>
<sect2 id='obj-light'>
<title>Light Sources</title>
<para>
Every object node has the ability to become a light source and light the world. A light source on an object
is simply defined by giving it three floating point values that determine how much light is emitted in each
of the primary colors red, green and blue. These values are interpreted so that a perpendicular surface at
a distance of 1.0 unit from a light source whose intensity (in any color) is 1.0 gets a light level of 1.0
(as <quote>seen</quote> by a material node's light fragment, that is).
</para>
<para>
By default, the light intensity is set to 0.0 for all three colors. This means that no light is emitted.
</para>
<para>
The light described here is a simple <quote>point light</quote>, with an equal amount of light being emitted
in each direction spherically, centered on the object's position. To create a more sophisticated light,
create a link to a <link linkend='n-geometry'>geometry node</link> and label it <quote><literal>light</literal></quote>.
This has the semantics of defining an area light, which only emits light from the faces of the geometry.
</para>
<sidebar>
<title>API Link</title>
<para>Object light is set using the <xref linkend='verse_send_o_light_set'/> function.</para>
</sidebar>
</sect2>
<sect2 id="o-methods">
<title>Methods</title>
<para>
The object node has the ability to hold custom entry points, known as <emphasis>methods</emphasis>. Methods are
like procedures in a programming language, they are a representation of the abstract concept of a named
action that takes a set of parameters and can be executed (called) at will. Methods are arranged in the node
into a number of named <emphasis>groups</emphasis>. They do not have return values, and are thus asynchronous
in nature.
</para>
<para>
Once created, method calls can be emitted by any client and any client is free to respond to a method being
called. This mechanism allows clients to create representations of their interfaces inside the world held on
the host.
</para>
<sidebar>
<title>API Links</title>
<para>Object methods are manipulated using the
<xref linkend='verse_send_o_method_group_create'/>, <xref linkend='verse_send_o_method_group_destroy'/>, <xref linkend='verse_send_o_method_group_subscribe'/>,
<xref linkend='verse_send_o_method_group_unsubscribe'/>, <xref linkend='verse_send_o_method_create'/>, <xref linkend='verse_send_o_method_destroy'/> and
<xref linkend='verse_send_o_method_call'/> functions.
</para>
</sidebar>
</sect2>
<sect2 id="o-animations">
<title>Animation</title>
<para>
Object nodes can be animated. Animation is expressed in the data model by creating <link linkend='geometry-bones'>
bones</link> in the object's <link linkend='n-geometry'>geometry node</link>, and also one or more
<link linkend='n-curve'>curve nodes</link>. Once the data is in place, you can instruct the object node
to <link linkend='o_anim_run'>run</link> the animation.
</para>
<sidebar>
<title>API Link</title>
<para>Object animations are controlled using the <xref linkend='verse_send_o_anim_run'/> function.</para>
</sidebar>
</sect2>
<sect2 id="o-hide">
<title>Hiding</title>
<para>
Object nodes can be selectively <emphasis>hidden</emphasis>. Hiding an object makes it invisible in the 3D
world. This is useful to cut down on latency and round-trips, by pre-defining content which can then be
rapidly made visible by just un-hiding the root object node.
</para>
<sidebar>
<title>API Link</title>
<para>Control an object's hidden status using the <xref linkend='verse_send_o_hide'/> function.</para>
</sidebar>
</sect2>
</sect1>

<sect1 id="n-geometry">
<title>The Geometry Node</title>
<para>
The Geometry node describes the shape of the geometry and any additional data that is assigned to the surface
of an object.
</para>
<para>
Verse has a single primitive when it comes to representing geometry: Catmull/Clark <emphasis>subdivision surfaces</emphasis>.
Subdivision allows a simple polygonal mesh to be refined, by letting the algorithm generate more polygons so
that the model finally becomes smooth. Rendering clients in Verse are free to apply subdivision to the meshes
stored, the <emphasis>intent</emphasis> is that they should in order to approach the ideal created by the
artist but they do not have to. Verse's subdivision surfaces support <emphasis>creases</emphasis> with which
one can control the degree of subdivision allowed for each vertex and edge.
</para>
<para>
The data held by a geometry node can be divided into vertex and polygon definitions. Vertex data describe positions
in a local 3D space, and polygons are created by referencing the vertices. All polygons have exactly three or four
corners (vertex references), there is no support for general N-sided polygons. There is always storage reserved for
four corners for a given polygon; if the three first references are valid and the fourth unused, the polygon is a
triangle. If also the fourth reference is to a valid vertex, it is a quadrillion. All polygons are two-sided, and
the front side references its vertices in a clockwise manner.
</para>
<sect2>
<title>Layers</title>
<para>
The geometry data is stored in <emphasis>layers</emphasis>, where each layer has a well-defined type. There are
layer types for storing data per vertex, per polygon corner, and per polygon face. <xref linkend="g-layer-table"/>
is a table that summarizes the available layer formats.
<table align="center" id="g-layer-table">
<title>Geometry Node Layer Types</title>
<tgroup cols="5" align="center">
<thead>
<row rowsep='1'>
 <entry>Name</entry>
 <entry>Enum Value</entry>
 <entry>Value Type</entry>
 <entry>Value Size, bits</entry>
 <entry>Values per Index</entry>
</row>
</thead>
<tbody>
<row>
 <entry align="right"><symbol>VN_G_LAYER_VERTEX_XYZ</symbol></entry><entry><literal>0</literal></entry>
 <entry>Floating Point</entry>
 <entry>64</entry>
 <entry>3</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_VERTEX_UINT32</symbol></entry><entry><literal>1</literal></entry>
 <entry>Unsigned Integer</entry>
 <entry>32</entry>
 <entry>1</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_VERTEX_REAL</symbol></entry><entry><literal>2</literal></entry>
 <entry>Floating Point</entry>
 <entry>64</entry>
 <entry>1</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_POLYGON_CORNER_UINT32</symbol></entry><entry><literal>128</literal></entry>
 <entry>Unsigned Integer</entry>
 <entry>32</entry>
 <entry>4</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_POLYGON_CORNER_REAL</symbol></entry><entry><literal>129</literal></entry>
 <entry>Floating Point</entry>
 <entry>64</entry>
 <entry>4</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_POLYGON_FACE_UINT8</symbol></entry><entry><literal>130</literal></entry>
 <entry>Unsigned Integer</entry>
 <entry>8</entry>
 <entry>1</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_POLYGON_FACE_UINT32</symbol></entry><entry><literal>131</literal></entry>
 <entry>Unsigned Integer</entry>
 <entry>32</entry>
 <entry>1</entry>
</row>
<row>
 <entry align="right"><symbol>VN_G_LAYER_POLYGON_FACE_REAL</symbol></entry><entry><literal>132</literal></entry>
 <entry>Floating Point</entry>
 <entry>64</entry>
 <entry>1</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The first layer, named <quote><literal>vertex</literal></quote> but sometimes referred to as the
<quote>base layer</quote>, is always of type <symbol>VN_G_LAYER_VERTEX_XYZ</symbol>. The second layer is always
used to define the polygons of the subdivision mesh, and must have type <symbol>VN_G_LAYER_POLYGON_CORNER_UINT32</symbol>
and be named <quote><literal>polygon</literal></quote>. These two layers are rigidly defined since a host must be
able to perform validity checking on them, and thus must be able to uniquely identify which layer is the base vertex
layer and which defines the polygons. They are always present in every geometry node.
</para>
<para>
Any other layers can have whatever type is required by the application. More layers than the two basic ones are
often required, for instance to create a texture-mapped surface layers are added to hold the U and V components of
the texture coordinates that define the mapping.
</para>
<para>
The REAL-typed layers can be read and written using either 32 or 64 bits by clients, but always occupy 64 bits in
the host memory. By allowing 32-bit subscriptions, clients that do not need the full precision can reduce their
bandwidth demands.
</para>
<para>
The way to think about layers, is as two <quote>stacks</quote>, one for vertices and one for polygons. The vertex
stack always includes a <quote>base layer</quote> of type <literal>VN_G_LAYER_VERTEX_XYZ</literal> (with the numerical
ID 0 and the name <quote><literal>vertex</literal></quote>, while the polygon stack always has a
<literal>VN_G_LAYER_POLYGON_CORNER_UINT32</literal> layer (with ID 1, and name <quote><literal>polygon</literal></quote>).
Other layers, when created, will end up in one of the stacks depending on whether it is a vertex or polygon layer.
The size of all layers in a stack is controlled by the size of the base layer of that stack, i.e. one of the
aforementioned always-present layers. As vertices and/or polygons are created, the defining data (the XYZ coordinates
or the vertex references, respectively) are placed in a slot in the base layer, and all other layers are grown to
provide a slot of data space of whatever type the layer has for the new addition. This slot is typically initialized
with a default value, to make it well-defined until explicitly set.
</para>
<sidebar>
<title>API Links</title>
<para>
Geometry layers are manipulated using the
<xref linkend='verse_send_g_layer_create'/>, <xref linkend='verse_send_g_layer_destroy'/>, <xref linkend='verse_send_g_layer_subscribe'/>,
<xref linkend='verse_send_g_layer_unsubscribe'/> commands. Layer data is manipulated using the
<xref linkend='verse_send_g_vertex_set_xyz_real32'/>,
<xref linkend='verse_send_g_vertex_delete_real32'/>,
<xref linkend='verse_send_g_vertex_set_xyz_real64'/>,
<xref linkend='verse_send_g_vertex_delete_real64'/>,
<xref linkend='verse_send_g_vertex_set_uint32'/>,
<xref linkend='verse_send_g_vertex_set_real32'/>,
<xref linkend='verse_send_g_vertex_set_real64'/>,
<xref linkend='verse_send_g_polygon_set_corner_uint32'/>,
<xref linkend='verse_send_g_polygon_delete'/>,
<xref linkend='verse_send_g_polygon_set_corner_real32'/>,
<xref linkend='verse_send_g_polygon_set_corner_real64'/>,
<xref linkend='verse_send_g_polygon_set_face_uint32'/>,
<xref linkend='verse_send_g_polygon_set_face_real32'/> and
<xref linkend='verse_send_g_polygon_set_face_real64'/> functions.
</para>
</sidebar>
</sect2>
<sect2>
<title>Creases</title>
<para>
Crease information is used to control the subdivision algorithm, by specifying how sharp a crease a vertex
or edge should have it is possible to avoid getting all <quote>smoothed out</quote> objects. There are two
possible approached supported for the two creases: either they can all be set to a single constant, or crease
information can be stored in a layer and referenced that way. If a layer is used, it must be of type
<symbol>VN_G_LAYER_VERTEX_UINT32</symbol> for vertex creases, and <symbol>VN_G_LAYER_POLYGON_CORNER_UINT32</symbol>
for edges. These values are given the following interpretation: zero represents a smooth surface (no crease),
while <literal>MAX_UINT32</literal> should give the maximum amount of crease to the vertex or edge.
</para>

<para>
Vertex crease information is, as mentioned, stored in a regular <symbol>VN_G_LAYER_VERTEX_UINT32</symbol> layer. This
layer has room for one integer per vertex slot, which is exactly what is needed.
</para>
<para>
For polygon edges, however, perhaps
a bit more explanations are in order. The crease data is stored in a layer of type <symbol>VN_G_LAYER_POLYGON_CORNER_UINT32</symbol>.
Now, such a layer is normally used to associate values with the <emphasis>corners</emphasis> of the polygons, not with
their edges. But, since the difference is small here, and since Verse doesn't provide a specialized per-edge layer,
the layer is simply re-used. The way to interpret edge creases is can be stated like this: <quote>each corner holds the crease data
for the edge that starts in that corner</quote>.
</para>

<sidebar>
<title>API Links</title>
<para>Geometry crease data is set using the <xref linkend='verse_send_g_crease_set_vertex'/> and
<xref linkend='verse_send_g_crease_set_edge'/> functions.</para>
</sidebar>

</sect2>
<sect2 id='geometry-bones'>
<title>Bones</title>
<para>
The geometry node can also store local transformations known as <emphasis>bones</emphasis>. Bones are fairly complex in
their definition, with each bone having a numerical ID, a parent ID, weight and reference layer pointers, a position,
a position curve pointer, a rotation and a rotation curve pointer.
</para>
<para>
The numerical ID simply identifies each bone in the node, as with layer IDs. Bones are typically numbered from zero and
upwards, and the sequence of IDs will typically be kept <quote>tight</quote>, with as few gaps of unused IDs as possible.
</para>
<para>
The weight layer pointer is used to reference a layer that defines the influence of that particular bone on each vertex of
the model. Such layers must be of type <symbol>VN_G_LAYER_VERTEX_UINT32</symbol> or <symbol>VN_G_LAYER_VERTEX_REAL</symbol>.
Integer layers are interpreted as being in the range 0..1 by dividing each value by 4,294,967,295. The value in each slot
says how much the bone's transform affects the corresponding vertex.
</para>
<para>
The reference layer pointer is used to optimize space usage for large skeletons. Since the weights system above needs
one layer of weights for each bone, it ends up using a lot of storage space. This is especially true since skeletons
are typically local; the number of vertices influenced by each bone is typically small, and does not increase with
the number of bones or the number of vertices. Having to <quote>pay</quote> for them anyway adds a lot of overhead,
which is something to be avoided. The method used is to add another layer of indirection to the bone system. By
specifying the name of a <symbol>VN_G_LAYER_VERTEX_UINT32</symbol> layer in the reference field of a bone, this secondary
system is triggered. The layer should contain bone IDs, and the effect is that the weight values for the bone carrying
the reference are applied to the bones being referenced, rather than directly to the vertices. In this case, the
weight value carried in the bone definition no longer applies to the bone itself, but to any number of bones, as defined
by the reference layer.
</para>
<para>
The parent link defines hierarchies of bones, i.e. <emphasis>skeletons</emphasis>. It can be set to a non-existing bone to
indicate that no parent exists, and the bone will then be at root level.
</para>
<para>
The position and rotation properties of a bone can also be animated by linking them to <link linkend='n-curve'>curve node curves</link>.
This is done by specifying the name of the desired curves directly in the bone definition. When the named curve is
animated using the <link linkend='n-object'>object node</link> command, the bone referencing that curve will update.
</para>
<para>
Regarding the overall bone structure, the following simple <quote>algorithm</quote> might be helpful to illustrate how
they work. To draw a bone structure:
<itemizedlist>
<listitem><para>Take all the bone positions, and mark them out in 3D space.</para></listitem>
<listitem><para>Draw a line from every point to its parent, if it has one.</para></listitem>
</itemizedlist>
</para>
<para>Now you have something that looks like a bone structure, with the important (and typical) property that
if you rotate any bone, all bones <quote>downstream</quote> of it will rotate, too.</para>
<sidebar>
<title>API Links</title>
<para>Bones are manipulated using the <xref linkend='verse_send_g_bone_create'/> and <xref linkend='verse_send_g_bone_destroy'/> functions.</para>
</sidebar>
</sect2>
<sect2>
<title>Examples</title>
<para>
Because the geometry node is fairly complex, yet used for a very central and important purpose, it is helpful to illustrate
how it is used with the help of some simple examples. Such examples almost have to be very simple, since listing in full
the geometry for any <quote>realistic</quote> scene would swamp this document and still be unreadable.
</para>
<example>
<title>Cube Geometry</title>
<para>
One of the simplest 3D objects that is still interesting is the cube. A minimal cube consists of eight vertices and six
polygons (if using quadrilaterals, which is always recommended with Verse). To be well-defined in Verse, a cube also needs
its crease information set in a way that makes all edges and corners sharp. So, to summarize:
<itemizedlist>
<listitem><para>Eight vertices</para></listitem>
<listitem><para>Six quadrilaterals</para></listitem>
<listitem><para>Sharp creasing</para></listitem>
</itemizedlist>
That's all there is to building a cube. Let's attack these one at a time:
</para>
<para>
The vertices are stored in the standard <quote>vertex</quote> layer, with ID zero. They can be listed in any order,
but using the first eight slots is natural and the most space-efficient way to do it. Here is a table showing one possible
solution:
<informaltable>
<tgroup cols='9'>
<thead>
 <row>
  <entry align='center'>Layer</entry>
  <entry align='center'>0</entry>
  <entry align='center'>1</entry>
  <entry align='center'>2</entry>
  <entry align='center'>3</entry>
  <entry align='center'>4</entry>
  <entry align='center'>5</entry>
  <entry align='center'>6</entry>
  <entry align='center'>7</entry>
 </row>
</thead>
<tbody>
 <row>
  <entry>0 (<quote>vertex</quote>)</entry>
  <entry>(-1,1,-1)</entry>
  <entry>(1,1,-1)</entry>
  <entry>(1,1,1)</entry>
  <entry>(-1,1,1)</entry>
  <entry>(-1,-1,1)</entry>
  <entry>(1,-1,1)</entry>
  <entry>(1,-1,-1)</entry>
  <entry>(-1,-1,-1)</entry>
 </row>
</tbody>
</tgroup>
</informaltable>
Here, the four first vertices outline the top quadrilateral, in clock-wise order when seen from the outside. The last four
do the same for the bottom quadrilateral. Note how each cell (<quote>slot</quote> in the layer) contains three values,
this is because the layer has type <symbol>VN_G_LAYER_XYZ</symbol>.
</para>
<para>
Next, we need to define the polygons. This is done in the layer with ID=1, called <symbol>polygon</symbol>. Here is
how it could look, in tabular form:
<informaltable>
<tgroup cols='7'>
<thead>
 <row>
  <entry align='center'>Layer</entry>
  <entry align='center'>0</entry>
  <entry align='center'>1</entry>
  <entry align='center'>2</entry>
  <entry align='center'>3</entry>
  <entry align='center'>4</entry>
  <entry align='center'>5</entry>
 </row>
</thead>
<tbody>
 <row>
  <entry>1 (<quote>polygon</quote>)</entry>
  <entry>0,1,2,3</entry>
  <entry>4,5,6,7</entry>
  <entry>3,2,5,4</entry>
  <entry>2,1,6,5</entry>
  <entry>1,0,7,6</entry>
  <entry>0,3,4,7</entry>
 </row>
</tbody>
</tgroup>
</informaltable>
Each slot contains four integer values, since the type of the polygon layer is <symbol>G_POLYGON_CORNER_UINT32</symbol>.
The first two polygons are the top and bottom surfaces, respectively. They are followed by the front, right, back
and left surfaces of the cube (when viewed along the negative Z-axis, with positive Y being upwards). Each quadrilateral
is defined in clock-wise order, with the top left vertex first (when applicable).
</para>
<para>
Note how the vertex and polygon layers have different sizes. Although they are part of the same physical layer ID space
inside the node, they really do form two separate <quote>stacks</quote> of layers. All vertex layers will have the same
size as the base (ID=0) vertex layer, while all polygon layers will have the same size as the base (ID=1) polygon layer.
</para>
<para>
To help visualize the above, here is a figure showing a simple cube, with vertices labeled according to the order used above:
<figure id="g-ex-cube" float='1' floatstyle='right' pgwide='0'>
<title>A Cube</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/geometry/cube.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
The polygons are not marked in this figure, to reduce the clutter. The cube is viewed as described above, and the
XYZ axes use red, green and blue colors, respectively.
</para>
<para>
The final point we need to take care of is the creasing. To make sure the cube is not interpreted as a smooth
shape, we need to explicitly set the creasing to <quote>sharp</quote> for all vertices and edges. Crease information
can be stored in vertex and polygon layers, when finer control is needed, but there is also a way to set the default
to use for corners and edges, respectively. In this case, we need all the crease values to be the same, so we can use
the defaults and set them to <literal>0xffffffff</literal> which means <quote>maximum sharpness everywhere</quote>.
</para>
</example>

<!--
<example>
<title>Creased Geometry</title>
<para>
Nothing to see here.
</para>
</example>
-->

</sect2>
</sect1>

<sect1 id="n-material">
<title>The Material Node</title>
<para>
The material node is used to define surface properties of an object. It does this by defining a set of primitives,
known as <emphasis>fragments</emphasis>. Fragments are operators that process triplets of values, very suitable
for representing color but also re-usable for other properties of a surface. For colors, the standard interpretation
of a value is that 0 is black and 1 is white, but values can be outside this range (at both ends) without being
clipped or considered invalid.
</para>
<para>
To define e.g. color (the typical use for a material node), begin by creating an
output fragment, setting its type to <quote>color</quote>, and then create any further fragments as desired, linking
them to the root and each other to form the final material tree. The tree is then evaluated for every point of each
surface that uses that material, and the result used to control the final shading.
</para>
<sect2>
<title>Fragments</title>
<para>
<xref linkend="m-frags-enum"/> enumerates the defined fragment types, and also gives the numerical value associated
with each one. This number is used to identify a fragment type in the network protocol.
<table id="m-frags-enum">
<title>Material Node Fragment Type Enumeration</title>
<tgroup cols="3" align="center">
 <thead><row><entry>Name</entry><entry>Enum Value</entry><entry>Purpose</entry></row></thead>
 <tbody>
  <row><entry><link linkend="m-f-color"><symbol>VN_M_FT_COLOR</symbol></link></entry>
    <entry><literal>0</literal></entry>
    <entry align="left">Emits a constant color.</entry></row>
  <row><entry><link linkend="m-f-light"><symbol>VN_M_FT_LIGHT</symbol></link></entry>
    <entry><literal>1</literal></entry>
    <entry align="left">Represents light falling on a surface.</entry></row>
  <row><entry><link linkend="m-f-reflection"><symbol>VN_M_FT_REFLECTION</symbol></link></entry>
    <entry><literal>2</literal></entry>
    <entry align="left">Represents reflected light.</entry>
  </row>
  <row><entry><link linkend="m-f-transparency"><symbol>VN_M_FT_TRANSPARENCY</symbol></link></entry>
    <entry><literal>3</literal></entry>
    <entry align="left">Represents a transparent surface.</entry>
  </row>
  <row><entry><link linkend="m-f-volume"><symbol>VN_M_FT_VOLUME</symbol></link></entry>
    <entry><literal>4</literal></entry>
    <entry align="left">Represents a volume diffusion.</entry>
  </row>
  <row><entry><link linkend="m-f-view"><symbol>VN_M_FT_VIEW</symbol></link></entry>
    <entry><literal>5</literal></entry>
    <entry align="left">Represents the vector between camera and surface.</entry>
  </row>
  <row><entry><link linkend="m-f-geometry"><symbol>VN_M_FT_GEOMETRY</symbol></link></entry>
    <entry><literal>6</literal></entry>
    <entry align="left">Uses data from a geometry layer to create color.</entry>
  </row>
  <row><entry><link linkend="m-f-texture"><symbol>VN_M_FT_TEXTURE</symbol></link></entry>
    <entry><literal>7</literal></entry>
    <entry align="left">Does look-ups in a bitmap node.</entry>
  </row>
  <row><entry><link linkend="m-f-noise"><symbol>VN_M_FT_NOISE</symbol></link></entry>
    <entry><literal>8</literal></entry>
    <entry align="left">Generates random noise.</entry>
  </row>
  <row><entry><link linkend="m-f-blender"><symbol>VN_M_FT_BLENDER</symbol></link></entry>
    <entry><literal>9</literal></entry>
    <entry align="left">Blends two inputs together.</entry>
  </row>
  <row><entry><link linkend="m-f-clamp"><symbol>VN_M_FT_CLAMP</symbol></link></entry>
    <entry><literal>10</literal></entry>
    <entry align="left">Clamps input to a minimum or maximum value.</entry>
  </row>
  <row><entry><link linkend="m-f-matrix"><symbol>VN_M_FT_MATRIX</symbol></link></entry>
    <entry><literal>11</literal></entry>
    <entry align="left">Transforms input through a matrix.</entry>
  </row>
  <row><entry><link linkend="m-f-ramp"><symbol>VN_M_FT_RAMP</symbol></link></entry>
    <entry><literal>12</literal></entry>
    <entry align="left">Interpolates in a table.</entry>
  </row>
  <row><entry><link linkend="m-f-animation"><symbol>VN_M_FT_ANIMATION</symbol></link></entry>
    <entry><literal>13</literal></entry>
    <entry align="left">Interpolates in a table.</entry>
  </row>
  <row><entry><link linkend="m-f-alternative"><symbol>VN_M_FT_ALTERNATIVE</symbol></link></entry>
    <entry><literal>14</literal></entry>
    <entry align="left">Allows implementation to select between two alternatives.</entry>
  </row>
  <row><entry><link linkend="m-f-output"><symbol>VN_M_FT_OUTPUT</symbol></link></entry>
    <entry><literal>15</literal></entry>
    <entry align="left">The root of each material fragment graph, the final output.</entry>
  </row>
 </tbody>
</tgroup>
</table>
</para>

<para>
<xref linkend="m-frags-table"/> presents the defined fragment types. It mentions the purpose of each one,
including its input fields and what operation it performs to generate its emitted color. Click the fragment
name to jump into the table below, for a more detailed explanation.
</para>
<para>
These are the types of <link linkend='m-f-output'>output</link> fragment that are currently defined:
<variablelist>
<varlistentry>
<term><literal>color</literal></term>
<listitem><para>The tree defines surface color. This is the most common use.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>displacement</literal></term>
<listitem><para>Displacement of a surface. Gives a displacement along the surface normal, with a displacement
distance exactly equal to the average of the sum of the components of the triplet reaching the output fragment.
In other words, the distance is (R+G+B)/3. This should be done in the coordinate space of the geometry being
displaced.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>audio</literal></term>
<listitem><para>This is pending, and has not yet been given a final interpretation.</para></listitem>
</varlistentry>
</variablelist>

<table id="m-frags-table">
<title>Material Node Fragment Type Descriptions</title>
<tgroup cols="2" align="center">
<thead>
<row>
 <entry>Name</entry>
 <entry>Description</entry>
</row>
</thead>
<tbody>

<row>
 <entry>Color</entry>
 <entry align="left">
  <anchor id="m-f-color"/><para>The color fragment emits a single constant floating point triplet, generally used to represent a
RGB color. It is defined by three simple fields:</para>
  <variablelist>
   <varlistentry>
    <term><type>real64</type> <varname>red</varname></term>
    <listitem><para>The red component of the color being emitted by this fragment.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>green</varname></term>
    <listitem><para>The green component of the color being emitted by this fragment.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>blue</varname></term>
    <listitem><para>The blue component of the color being emitted by this fragment.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Light</entry>
 <entry align="left">
  <anchor id="m-f-light"/><para>The light fragment represents the amount of incoming light at a given point on a surface.
It does not compute any view-dependent reflective properties of the surface, unless the BRDF field
is used. The normal falloff ranges from zero to one, and defines the micro-geometry of the surface.
A value of zero represents a perfectly flat surface, while a value of one represents a surface whose
normals are randomly distributed.
  </para>
  <para>
  <variablelist>
   <varlistentry>
    <term><type>enum</type> <varname>type</varname></term>
    <listitem><para>The type of light computation the fragment represents. See <xref linkend="m-light"/> below.
     </para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>normal_falloff</varname></term>
    <listitem><para>Describes the smoothness of the surface.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>node</type> <varname>brdf</varname></term>
    <listitem><para>A node.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>brdf_r</varname></term>
    <listitem><para>A red something.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>brdf_g</varname></term>
    <listitem><para>A green something.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>brdf_b</varname></term>
    <listitem><para>A blue something.</para></listitem>
   </varlistentry>
  </variablelist>
   <table id="m-light">
    <title>Light Types</title>
    <tgroup cols='3'>
     <thead>
      <row><entry>Type Name</entry><entry>Value</entry><entry>Description</entry></row>
     </thead>
     <tbody>
      <row><entry><symbol>M_LIGHT_DIRECT</symbol></entry><entry align="center">0</entry>
       <entry>The light falling directly on to a surface.</entry></row>
      <row><entry><symbol>M_LIGHT_AMBIENT</symbol></entry><entry align="center">1</entry>
       <entry>The environment's ambient light.</entry></row>
      <row><entry><symbol>M_LIGHT_DIRECT_AND_AMBIENT</symbol></entry><entry align="center">2</entry>
       <entry>Both direct and ambient light, added together.</entry></row>
      <row><entry><symbol>M_LIGHT_BACK</symbol></entry><entry align="center">3</entry>
       <entry>The light that falls upon the back side of the material.</entry></row>
     </tbody>
     </tgroup>
   </table>
  </para>
 </entry>
</row>

<row>
 <entry>Reflection</entry>
 <entry align="left">
  <anchor id="m-f-reflection"/><para>This fragment represents a view-dependent perfect reflection computation from
the evaluation point. The normal fall-off describes the micro-geometry in the same manner used by the
<link linkend="m-f-light">light</link> fragment.
  </para>
  <variablelist>
   <varlistentry>
    <term><type>real64</type> <varname>normal_falloff</varname></term>
    <listitem><para>Something.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Transparency</entry>
 <entry align="left">
  <anchor id="m-f-transparency"/><para>This fragment represents the properties of the surface that is behind the
evaluation point. The refraction index represent how light is bent when passing through the surface, and the normal
fall-off describes the micro-geometry just as in the <link linkend="m-f-light">light</link> and
<link linkend="m-f-reflection">reflection</link> fragments.
  </para>
  <variablelist>
   <varlistentry>
    <term><type>real64</type> <varname>normal_falloff</varname></term>
    <listitem><para>Something.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>refraction_index</varname></term>
    <listitem><para>The refraction index of the material. Obviously not trivial to implement.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Volume</entry>
 <entry align="left">
  <anchor id="m-f-volume"/><para>This fragment represents the volume of air between the light source and the point
on the surface being shaded. It allows you to model non-clear air, by specifying a color that will be weighted in
according to the distance travelled through the volume.
  </para>
  <variablelist>
   <varlistentry>
    <term><type>real64</type> <varname>diffusion</varname></term>
    <listitem><para></para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>col_r</varname></term>
    <listitem><para></para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>col_g</varname></term>
    <listitem><para></para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>real64</type> <varname>col_b</varname></term>
    <listitem><para></para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>View</entry>
 <entry align="left">
  <anchor id="m-f-view"/><para>This fragment simply generates a vector pointing from the point at the surface,
directly towards the viewing position. It can be thought of as the surface's normal, transformed by the view
matrix. For a point on the surface facing straight towards the camera, it will be (0, 0, 1). For a face
facing to the left, it will be (1, 0, 0), and so on.</para>
<para>
The fragment itself is empty, i.e. it has no parameters.
</para>
 </entry>
</row>

<row>
 <entry>Geometry</entry>
 <entry align="left">
  <anchor id="m-f-geometry"/><para>The geometry fragment allows a material to reference properties defined in a
<link linkend="n-geometry">geometry node</link>. Any layer can be referenced, integer layers will be converted
to normalized floating-point (by dividing with the maximum for the type in question). If an XYZ-type layer is
being referenced, the values will be mapped to the RGB data space fragments use trivially (X becomes red, Y
becomes green, and Z becomes blue). These are the fields of the fragment:
  </para>
  <variablelist>
   <varlistentry>
    <term><type>string</type> <varname>layer_r</varname></term>
    <listitem><para>Which layer to use as source of red-channel values.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>layer_g</varname></term>
    <listitem><para>Which layer to use as source of green-channel values.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>layer_b</varname></term>
    <listitem><para>Which layer to use as source of blue-channel values.</para></listitem>
   </varlistentry>
  </variablelist>
  <para>
  There is no node reference in this fragment; this is because the layers being referenced are always
(implicitly) taken to be in the current object's geometry node. This is typically the only practical
approach anyway, since e.g. UV-mapping data must be closely coupled to the geometry data in order to
be applicable; referencing layers in the same node helps ensure this.
  </para>
 </entry>
</row>

<row>
 <entry>Texture</entry>
 <entry align="left">
  <anchor id="m-f-texture"/><para>The texture fragment uses the incoming color as a point in 3D space mapped onto
a bitmap, and returns the value of the pixel at that point. It is used, with the <link linkend="m-f-geometry">geometry
fragment</link>, to express plain old texture-mapping. It has the following fields:
  </para>
  <variablelist>
   <varlistentry>
    <term><type>node</type> <varname>bitmap</varname></term>
    <listitem><para>A bitmap node to read texture data from.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>layer_r</varname></term>
    <listitem><para>Which layer to use as source of red-channel values.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>layer_g</varname></term>
    <listitem><para>Which layer to use as source of green-channel values.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>string</type> <varname>layer_b</varname></term>
    <listitem><para>Which layer to use as source of blue-channel values.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>boolean</type> <varname>filtered</varname></term>
    <listitem><para>Is the texture to be filtered when viewed up close?</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>control</varname></term>
    <listitem><para>The ID of a fragment whose output is used as the mapping, see above.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Noise</entry>
 <entry align="left">
  <anchor id="m-f-noise"/><para>The noise fragment takes a single input color, and uses it as a lookup in a
noise function. These are the types of noise currently supported:
<table>
 <title>Noise Fragment Types</title>
 <tgroup cols='3'>
  <thead>
   <row><entry>Type Name</entry><entry>Value</entry><entry>Generated Noise</entry></row>
  </thead>
  <tbody>
   <row><entry><symbol>M_NOISE_PERLIN_ZERO_TO_ONE</symbol></entry><entry><literal>0</literal></entry><entry>Noise distributed in the
numerical range [0,1] inclusive.</entry></row>
   <row><entry><symbol>M_NOISE_PERLIN_MINUS_ONE_TO_ONE</symbol></entry><entry><literal>1</literal></entry>
  <entry>Noise distributed in the numerical range [-1,1] inclusive.</entry></row>
   <row><entry><symbol>M_NOISE_POINT_ZERO_TO_ONE</symbol></entry><entry><literal>2</literal></entry>
  <entry>Noise, in range [0,1] inclusive.</entry></row>
   <row><entry><symbol>M_NOISE_POINT_MINUS_ONE_TO_ONE</symbol></entry><entry><literal>2</literal></entry>
  <entry>Noise in range [-1,1] inclusive.</entry></row>
  </tbody>
 </tgroup>
</table>
  </para>
  <variablelist>
   <varlistentry>
    <term><type>enum</type> <varname>type</varname></term>
    <listitem><para>The type of noise to generate. A value from the table above.
    </para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>mapping</varname></term>
    <listitem><para>Input coordinate that is looked up in (or fed to) the noise function.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Blender</entry>
 <entry align="left">
  <anchor id="m-f-blender"/><para>The blender fragment takes two input colors A and B (and sometimes a control
input), and blends them using a function chosen from the following list:
   <table>
    <title>Blender Fragment Types</title>
    <tgroup cols='3'>
     <thead>
      <row><entry>Type Name</entry><entry>Value</entry><entry>Function</entry></row>
     </thead>
     <tbody>
      <row><entry><symbol>M_BLEND_FADE</symbol></entry><entry align="center">0</entry>
       <entry>A * control + B * (1 - control)</entry></row>
      <row><entry><symbol>M_BLEND_ADD</symbol></entry><entry align="center">1</entry>
       <entry>A + B</entry></row>
      <row><entry><symbol>M_BLEND_SUBTRACT</symbol></entry><entry align="center">2</entry>
       <entry>A - B</entry></row>
      <row><entry><symbol>M_BLEND_MULTIPLY</symbol></entry><entry align="center">3</entry>
       <entry>A * B</entry></row>
      <row><entry><symbol>M_BLEND_DIVIDE</symbol></entry><entry align="center">4</entry>
       <entry>A / B</entry></row>
     </tbody>
     </tgroup>
   </table>
  </para>
  <variablelist>
   <varlistentry>
    <term><type>enum</type> <varname>type</varname></term>
    <listitem><para>The type of blend to produce. One of the values listed above.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>data_a</varname></term>
    <listitem><para>The <quote>A</quote> source data.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>data_b</varname></term>
    <listitem><para>The <quote>B</quote> source data.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>control</varname></term>
    <listitem><para>The <quote>control</quote> data needed for the <literal>M_BLEND_FADE</literal> mode.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Clamp</entry>
 <entry align="left">
  <anchor id="m-f-clamp"/><para>The clamp fragment limits its input value, by computing the <literal>min()</literal>
or <literal>max()</literal> function on the input and a constant. It is useful for instance to eliminate negative
numbers from blending equations. The function is computed separately for each of the three channels.</para>
<note>
<para>
It is easy to confuse oneself when thinking about the clamp fragment. It helps to just keep in mind that it
computes the standard <literal>min()</literal> or <literal>max()</literal> function, and nothing else. For instance,
to make sure an input is kept to at <emphasis>most</emphasis> (0.5, 0.5, 0.5), set the clamp's <literal>min</literal>
value to <literal>true</literal>, thus computing the <literal>min()</literal> function, which has the desired result.
</para>
</note>
 <variablelist>
  <varlistentry>
   <term><type>boolean</type> <varname>min</varname></term>
   <listitem><para>If <literal>true</literal>, the fragment computes the <literal>min()</literal> function,
else it computes <literal>max()</literal>.</para></listitem>
  </varlistentry>
  <varlistentry>
   <term><type>real64</type> <varname>red</varname></term>
   <listitem><para>Red component of limit value.</para></listitem>
  </varlistentry>
  <varlistentry>
   <term><type>real64</type> <varname>green</varname></term>
   <listitem><para>Green component of limit value.</para></listitem>
  </varlistentry>
  <varlistentry>
   <term><type>real64</type> <varname>blue</varname></term>
   <listitem><para>Blue component of limit value.</para></listitem>
  </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>data</varname></term>
    <listitem><para>The input data that is to be clamped.</para></listitem>
   </varlistentry>
 </variablelist>
 </entry>
</row>

<row>
 <entry>Matrix</entry>
 <entry align="left">
  <anchor id="m-f-matrix"/><para>The matrix fragment runs its input values through a 4x4 transformation matrix.
Since the data passed between fragments is defined to be only triplets, they are considered extended with a
fourth element with the value zero for these purposes. This element is then dropped again, since the data
flowing between material fragments is only three components (RGB color). Of course, you can also think of it
as just ignoring the last row and column of the matrix, and doing the operation on the 3x3 upper-left sub matrix.
  </para>
  <para>
The operation is a post-multiplication of the matrix by the color, e.g. output = matrix &times; color.
  </para>
  <variablelist>
   <varlistentry>
    <term><type>array of real64</type> <varname>matrix</varname></term>
    <listitem><para>The matrix itself, defined as 16 floating point values in row-major order.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>data</varname></term>
    <listitem><para>The input data to transform.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Ramp</entry>
 <entry align="left">
  <anchor id="m-f-ramp"/><para>A ramp (or curve) defined as an array of (position,color) tuples.
It takes a color as input, and selects a single channel. The value of that channel is then used to do
an interpolating look-up in the ramp, and the resulting color is emitted. A ramp essentially maps a
one-dimensional input value into the three-dimensional color space.
<table id='m-f-ramp-type'>
 <title>Ramp Fragment Types</title>
 <tgroup cols='3'>
  <thead>
   <row><entry>Type Name</entry><entry>Value</entry><entry>Ramp Interpolation</entry></row>
  </thead>
  <tbody>
   <row><entry><symbol>M_RAMP_SQUARE</symbol></entry><entry><literal>0</literal></entry>
    <entry>Do no interpolation, just pick whatever value is closest in the ramp.</entry></row>
   <row><entry><symbol>M_RAMP_LINEAR</symbol></entry><entry><literal>1</literal></entry>
    <entry>Interpolate linearly between neighboring ramp values.</entry></row>
   <row><entry><symbol>M_RAMP_SMOOTH</symbol></entry><entry><literal>2</literal></entry>
    <entry>Interpolate bi-linearly between ramp elements.</entry></row>
  </tbody>
 </tgroup>
</table>
<table id='m-f-ramp-channel'>
 <title>Ramp Channel Types</title>
 <tgroup cols='3'>
  <thead>
   <row><entry>Type Name</entry><entry>Value</entry><entry>Channel Selection</entry></row>
  </thead>
  <tbody>
   <row><entry><symbol>M_RAMP_RED</symbol></entry><entry><literal>0</literal></entry>
    <entry>Use the red component of incoming values to do the look-up.</entry></row>
   <row><entry><symbol>M_RAMP_GREEN</symbol></entry><entry><literal>1</literal></entry>
    <entry>Use the green component of incoming values to do the look-up.</entry></row>
   <row><entry><symbol>M_RAMP_BLUE</symbol></entry><entry><literal>2</literal></entry>
    <entry>Use the blue component of incoming values to do the look-up.</entry></row>
  </tbody>
 </tgroup>
</table>
 </para>
  <variablelist>
   <varlistentry>
    <term><type>enum</type> <varname>type</varname></term>
    <listitem><para>The type of interpolation desired in this ramp. Must be a value from
<xref linkend='m-f-ramp-type'/> above.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>enum</type> <varname>channel</varname></term>
    <listitem><para>Which channel of the input should be used to do the look-up. Must be a value from
<xref linkend='m-f-ramp-channel'/> above.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term>array of (<type>real64</type> <varname>position,red,green,blue</varname>) <varname>ramp</varname></term>
<listitem><para>The ramp data itself. A maximum of 48 data points can be specified in a single ramp.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Animation</entry>
 <entry align="left">
  <anchor id="m-f-animation"/>
  <para></para>
  <variablelist>
   <varlistentry>
    <term><type>string</type> <varname>label</varname></term>
    <listitem><para></para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Alternative</entry>
 <entry align="left">
  <anchor id="m-f-alternative"/><para>This fragment specifies two inputs, and allows the parser to select one and
ignore the other. The most preferable path should always be specified as the one labeled A. The intent is to allow
e.g. simpler materials to be defined in an alternative path. It is not defined how a shading implementation is
supposed to chose between the two, it is left up to the implementor.
  </para>
  <variablelist>
   <varlistentry>
    <term><type>fragment</type> <varname>alt_a</varname></term>
    <listitem><para>Alternative path A, the most preferable one.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><type>fragment</type> <varname>alt_b</varname></term>
    <listitem><para>Alternative path B, the least preferable one.</para></listitem>
   </varlistentry>
  </variablelist>
 </entry>
</row>

<row>
 <entry>Output</entry>
 <entry align="left">
  <anchor id="m-f-output"/><para>The output fragment serves as the root for a material tree, and must be present
in a material node in order for it to have any effect. It is defined by the following fields:</para>
  <variablelist>
   <varlistentry>
    <term><type>string</type> <varname>type</varname></term>
    <listitem><para>What type of surface property is described by this output fragment.
See above for a list of the defined, well-known, output types.
</para></listitem>
   </varlistentry>
   <varlistentry>
    <term>fragment <varname>front</varname></term>
    <listitem><para>The ID of the fragment which defines the surface property for the front
side of polygons using this material.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term>fragment <varname>back</varname></term>
    <listitem><para>The ID of the fragment which defines the surface property for the back
side of polygons using this material.</para></listitem>
   </varlistentry>
  </variablelist>
  <para>
  If the <varname>front</varname> field is given a valid, non-zero value, any surface using this material will
show it on its forward-facing side. If the <varname>back</varname> field is given a valid, non-zero value, it
will show up on the backward-facing sides. If <varname>front</varname> equals <varname>back</varname> and is the
ID of a valid fragment, the material will be double-sided. Leaving either <varname>front</varname> or
<varname>back</varname> set to zero (an invalid fragment ID) or set to an invalid value will make the
corresponding side of surfaces invisible.
  </para>
 </entry>
</row>

</tbody>
</tgroup>
</table>
</para>
<sidebar>
<title>API Links</title>
<para>Material fragments are manipulated using the <xref linkend='verse_send_m_fragment_create'/> and <xref linkend='verse_send_m_fragment_destroy'/> functions.</para>
</sidebar>
</sect2>
<sect2>
<title>Examples</title>
<para>
This section contains a set of example fragment graphs, to illustrate how the various pieces of functionality
can be used together to create various actual materials.
</para>
<example>
<title>Plain Gray</title>
<para>
<figure id="m-ex-plain-gray">
<title>A Plain Gray Material</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/material/plain-gray.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
<xref linkend="m-ex-plain-gray"/> shows a simple two-fragment material. This is about as simple as a material
can become, since a lone <link linkend="m-f-output">output</link> fragment is of little use. The added
<link linkend="m-f-color">color</link> fragment provides a constant medium-gray color for the entire surface.
This material will not be very realistic, for example it will not react to incoming light at all.
</para>
<para>
The output fragment does not specify a value for the <varname>back</varname> field; meaning it's single-sided
(surfaces using this material will not be visible from their back side).
</para>
</example>
</sect2>
</sect1>

<sect1 id="n-bitmap">
<title>The Bitmap Node</title>
<para>
The bitmap node stores three-dimensional arrays of values. As the name implies, the intended use is to
store bitmap data, i.e. images. In a 3D-graphics system, images are usually used to <emphasis>texture</emphasis>
surfaces, so storing color data used for texturing is a common use for the bitmap node. It can also be used to
store other arrays of data needed to describe surface features, for things like displacement mapping, and of
course any application-specific data that is best expressed this way.
</para>
<para>
Bitmaps are often used as look-up tables for other operations, such as the texturing mentioned above. Since
these operations often need to use a relatively small amount of samples to cover a large screen area, filtering
techniques might need to be used to reduce artifacting by interpolating values between the ones present in
the bitmap itself.
</para>
<sect2>
<title>Bitmap Coordinates</title>
<para>
In their most general form, Verse bitmaps are three-dimensional <quote>cubes</quote> of samples (often called
<quote>pixels</quote>), with independent sizes in each of the three dimensions: width, height, and depth. They
can be restricted to only two or one dimension(s), which is frequently useful. Such a restriction is done by
setting the size in the required dimension(s) to one, and must be done from the end of dimension list. So, a
2D bitmap can only be created by setting the <emphasis>depth</emphasis> to one, not e.g. the height.
</para>
<para>
<figure id="b-ex-coords">
<title>Bitmap Coordinates</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/bitmap/coords.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
Coordinates are in a <quote>screen-like</quote> space, with three axis called x, y and z. The pixel at (0,0,0) is
the leftmost, topmost, and foremost pixel. <xref linkend='b-ex-coords'/> shows the coordinate system used for bitmaps.
The Z, or depth, axis, is intended to go <quote>into</quote> the document, making this a right-handed coordinate
system. The number of pixels contained in a bitmap is unknown when the node has just been created; it must be set
by the application, before any pixels can be stored in the bitmap. The width, height and depth of a bitmap are
colletively referred to as the bitmap's <emphasis>dimensions</emphasis>.
</para>
<sidebar>
<title>API Link</title>
<para>The dimensions of a bitmap node are set using the <xref linkend='verse_send_b_dimensions_set'/> function.</para>
</sidebar>
</sect2>

<sect2>
<title>Layers</title>
<para>
Data in a bitmap node is arranged into <emphasis>layers</emphasis>. A single layer stores a full three-dimensional
(or restricted, see above) image. All layers in a node have the same size, that of the node itself. This size can
be re-set at any point, making all the layers grow or shrink as needed. Shrinking a node after data is been supplied
will effectively <emphasis>crop</emphasis> the layer data, permanently losing the data that falls outside the new
size. Layers have names that must be unique within the node, and a <emphasis>type</emphasis> that is one of the
following:
<table align="center" id="b-layer-table">
<title>Bitmap Node Layer Types</title>
<tgroup cols="4" align="center">
<thead>
<row>
 <entry>Name</entry>
 <entry>Enum Value</entry>
 <entry>Value Type</entry>
 <entry>Value Size, bits</entry>
</row>
</thead>
<tbody>
<row>
 <entry align="right"><symbol>B_LAYER_UINT1</symbol></entry><entry><literal>0</literal></entry>
 <entry>uint16, packed</entry>
 <entry>1</entry>
</row>
<row>
 <entry align="right"><symbol>B_LAYER_UINT8</symbol></entry><entry><literal>1</literal></entry>
 <entry>uint8</entry>
 <entry>8</entry>
</row>
<row>
 <entry align="right"><symbol>B_LAYER_UINT16</symbol></entry><entry><literal>2</literal></entry>
 <entry>uint16</entry>
 <entry>16</entry>
</row>
<row>
 <entry align="right"><symbol>B_LAYER_REAL32</symbol></entry><entry><literal>3</literal></entry>
 <entry>real32</entry>
 <entry>32</entry>
</row>
<row>
 <entry align="right"><symbol>B_LAYER_REAL64</symbol></entry><entry><literal>4</literal></entry>
 <entry>real64</entry>
 <entry>64</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Integer values are interpreted as being in the range of zero to one by dividing with the maximum value for
the respective sizes. Floating point values are not clamped to any range.
<note>
 <title>Expressing Color</title>
 <para>Since layers only provide a single value per pixel, you cannot express a typical RGB image using
 a single layer. Such images are stored by splitting them into three layers, one for each of the color
 components.</para>
</note>
</para>
<para>
The <symbol>B_LAYER_UINT1</symbol> format is slightly special, since there is no 1-bit integer type defined
in Verse. As we will see in subsequent sections, pixels in a 1-bit layer are expressed using the bits of
a single uint16 value.
</para>
<sidebar>
<title>API Links</title>
<para>Bitmap layers are manipulated using the <xref linkend='verse_send_b_layer_create'/>, <xref linkend='verse_send_b_layer_destroy'/>,
<xref linkend='verse_send_b_layer_subscribe'/> and <xref linkend='verse_send_b_layer_unsubscribe'/> commands.</para>
</sidebar>
</sect2>
<sect2>
<title>Tiles</title>
<para>
The smallest individually addressable part of a bitmap layer is a <emphasis>tile</emphasis>. A tile is simply
a small flat (two-dimensional) square of pixels in the XY plane of a bitmap layer. The current standard tile size is
8x8 pixels. This size is fixed and the same for all Verse programs, it cannot be changed by client programmers. Tiles
make bulk transfer of bitmap data in a network more efficient, by reducing addressing overhead.
</para>
<para>
Each layer is split into tiles by simply dividing it into squares of 8x8 pixels, beginning in the top left corner.
This creates a <quote>tile coordinate system</quote>. If the bitmap's dimensions are not integer multiples of the
tile side length, eight, there will be tiles with only partial coverage of the bitmap. Any pixels in a tile
that fall outside of the bitmap itself will not be stored by the host, and should transmitted as zeroes when
transmission is at all required. Applications should not read them.
</para>
<para>
Each tile is addressed using its tile coordinates in 2D, plus a Z coordinate that locates the tile in the
third dimension if applicable. For a 2D bitmap, Z will always be zero. Note that there is no tiling in the
Z direction; a tile is a 2D flat 8x8-pixel square, with depth=1.
</para>
<sidebar>
<title>API Link</title>
<para>Bitmap pixel tiles are set using the <xref linkend='verse_send_b_tile_set'/> function.</para>
</sidebar>
</sect2>
</sect1>

<sect1 id="n-text">
<title>The Text Node</title>
<para>
The text node, predictably, is used to store text. This text is not interpreted or <quote>understood</quote>
in any way defined by this specification; it is purely intended for application-specific use (hopefully conforming
to an auxiliary standard or set of guidelines).
</para>
<para>
The intended use for text nodes is to store programs in source code format, that can be linked to objects in order
to provide them with scripted <quote>behaviors</quote> through the use of <link linkend="o-methods">object methods</link>.
</para>

<sect2>
<title>Language</title>
<para>
Each text node has a <emphasis>language</emphasis> field, which is simply a text string that names the language used
for the content of that node.
</para>
<para>
There is no default or <quote>native</quote> language specified in Verse; you are free to write clients to support
any language you chose, or to invent new languages. Such a client would typically implement a way for scripts to
access Verse by sending and receiving node commands, but need not mimic the reference implementation when doing so.
</para>
<para>
The language name <quote><literal>text</literal></quote> is reserved for text in natural languages. To specify a
single language, use a slash followed by an <ulink url="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO 639:1988</ulink>
standard code. Text in English would then be <quote><literal>text/en</literal></quote>.
</para>
<para>
For programming language names, it is advised that the name is chosen to include a version number and a part that
identifies the kind of Verse application programming interface used. This is because there may be multiple APIs
defined for a single language, and interpreter clients need to determine if they should attempt to interpret a
buffer or not. For instance, a file written in C and using the reference API might have a language string of
<quote><literal>C/std</literal></quote>. Text in XML as used by the <quote>Purple</quote> plug-in scripting
engine is given a language starting with <quote><literal>XML/purple</literal></quote>.
</para>
<sidebar>
<title>API Link</title>
<para>The language of a text node is set using the <xref linkend='verse_send_t_language_set'/> function.</para>
</sidebar>
</sect2>

<sect2>
<title>Buffers</title>
<para>
Data in a text node is arranged into <emphasis>buffers</emphasis>. A buffer can be thought of as simply a named
text file; it consists of a linear sequence of characters. The sequence can be indexed, beginning from 0 which is
the first character (if present).
</para>
<para>
Changing the content if a text buffer is done through a single command, called <link linkend='t_text_set'>t_text_set</link>.
This command is fairly powerful, it combines two operations into one:
<itemizedlist>
<listitem><para>Deleting a range of text.</para></listitem>
<listitem><para>Inserting new text.</para></listitem>
</itemizedlist>
Deleting text moves any text after the removed range closer to the start of the buffer, effectively replacing the range
with nothing. The new text is inserted at the beginning of the indicated range, moving any text following the range further
towards the end of the buffer. If no new text is specified, the command acts as a pure deletion. Likewise, if the the size of
the range to delete is 0, the command acts as a pure text-insertion operation. This command has been designed to support the
implementation of online text editing, which typically needs both deletion and insertion.
</para>
<para>
Here is an example showing the contents of a text buffer during the execution of a sequence of <symbol>t_text_set</symbol> commands:
<example>
 <title>The t_text_set Command</title>
 <para>
 Initially, the buffer is empty. We will show the text between square brackets, in an attempt to indicate the start and end clearly:
  <screen>[]</screen>
 At this point, we execute the command <literal>t_text_set</literal> with range <literal>[0,0)</literal>
<footnote>
 <para>
 Ranges are given in <literal>[start,end)</literal> notation. The interpretation is <quote>all characters from index
 <varname>start</varname> up to, but not including, index <varname>end</varname></quote>. This means that the number
 of deleted characters is computed by <literal>end - start</literal>, and this that a range where <literal>start</literal> and
 <literal>end</literal> are the same, is empty.
 </para>
</footnote>
 and new text equal to <quote><literal>foorag</literal></quote>. Since the range is empty, this ends up being a straight
 insert, leaving the new state as simply the new text:
  <screen>[foorag]</screen>
 The next command to execute has range <literal>[3,3)</literal>, i.e. an empty range, and the text <quote><literal>ba</literal></quote>. We get:
 <screen>[foobarag]</screen>
 Finally, execute a command with range <literal>[6,8)</literal> and en empty new text, to delete the last two characters. Result:
 <screen>[foobar]</screen>
 </para>
</example>
</para>
<para>
It is important to realize that a single command is generally not enough to send the entire contents of a text buffer.
There is an inherent limit on the amount of data in a single command, for network efficiency reasons. For such buffers,
a sequence of commands will be required to send over the full content. For typical purposes, sending more than ~1,000
bytes of text per command should be avoided.
</para>
<sidebar>
<title>API Links</title>
<para>Text buffers are manipulated using the <xref linkend='verse_send_t_buffer_create'/>,
<xref linkend='verse_send_t_buffer_destroy'/>,
<xref linkend='verse_send_t_buffer_subscribe'/> and
<xref linkend='verse_send_t_buffer_unsubscribe'/> functions. Text is set using the <xref linkend='verse_send_t_text_set'/> function.</para>
</sidebar>
</sect2>
</sect1>

<sect1 id="n-curve">
<title>The Curve Node</title>
<para>
The curve node stores a set of curve definitions, defined as cubic &Bez; curves and optimized for dynamic
editing. The intended use is for animation, or other circumstances when there is a need to smoothly interpolate
a single parameter.
</para>
<sect2>
<title>Curves</title>
<para>
The content of a curve node is arranged into individual <emphasis>curves</emphasis>, with each curve having
its own content and being made available for subscription as single unit. Each curve is identified by a
numerical ID, just as with layers and buffers. Curves also have names, that must be unique within the same
node.
</para>
<para>
A curves expresses how a variable changes over time, by specifying control points to interpolate between. The
variable can be of one, two, three or four dimensions. Most examples below show the case for a one-dimensional
variable, in which case the entire curve can be visualized as an ordinary flat curve. Visualizing it for
more than one dimension can be done for instance by overlapping several such flat curves.
</para>
<para>
The way curves are used is by taking the value from a curve, and injecting it into some context to control
some parameter. For example, curves can be used to control <link linkend='geometry-bones'>bone transformations</link>,
creating smooth animation that is easily controlled by editing curves rather than complex transforms directly.
Or, they can be used to control aspects of materials, or the light emitted by an object.
</para>
<sidebar>
<title>API Links</title>
<para>Curves are manipulated using the <xref linkend='verse_send_c_curve_create'/>,
<xref linkend='verse_send_c_curve_destroy'/>, <xref linkend='verse_send_c_curve_subscribe'/> and
<xref linkend='verse_send_c_curve_unsubscribe'/> functions.</para>
</sidebar>
<sect3>
<title>Keys</title>
<para>
Each curve is made up of a set of <emphasis>key points</emphasis>, or keys for short. Taken all together,
the keys define the curve. A key is identified by the combination of the ID of the curve to which it belongs,
and an ID number for the key itself. A key is defined at a single position along the curve, and specifies
both the value and two helper <quote>wings</quote> that define how the value is changing before and after
they key. For a 2D curve, the wings specify the angle at which the curve enters and leaves the key point.
To summarize, we have:
<variablelist>
<varlistentry>
<term>(<type>real64</type> <varname>pos</varname>,<type>real64[DIM]</type> <varname>value</varname>)</term>
<listitem><para>
The key's position on the curve. This is an actual point, that the curve passes through. No two keys can
have the same <varname>pos</varname> value, they must all be unique. Keys can occur in any order, there
is no relation between the value of a key's numerical ID and its <varname>pos</varname> field.
</para></listitem>
</varlistentry>

<varlistentry>
<term>(<type>uint32[DIM]</type> <varname>pre_pos</varname>,<type>real64[DIM]</type> <varname>pre_delta</varname>)</term>
<listitem><para>
Specification for one of the <quote>wings</quote> of the curve point. This wing gives the direction of the
curve as it approaches the point from the left. In relative format, see below for how to compute actual
control point.
</para></listitem>
</varlistentry>

<varlistentry>
<term>(<type>uint32[DIM]</type> <varname>post_pos</varname>,<type>real64[DIM]</type> <varname>post_delta</varname>)</term>
<listitem><para>
Specification for the other <quote>wing</quote> on the curve point. This wing gives the direction in which
the curve exits the point, to the right. In relative format, see below for how to compute actual control point.
</para></listitem>
</varlistentry>
</variablelist>
In the above, a type name followed by <symbol>[DIM]</symbol> indicates that the field being described is
a vector, with <varname>DIM</varname> dimensions. All fields of a key are such, except the position. The
absolute position of a key is the same for all of its value's dimensions. The value of DIM is set when the
curve is created.
</para>
<para>
With these basic definitions out of the way, it is time to discuss how a curve is actually evaluated.
</para>
<sidebar>
<title>API Links</title>
<para>Curve keys are manipulated using the <xref linkend='verse_send_c_key_set'/> and <xref linkend='verse_send_c_key_destroy'/> functions.</para>
</sidebar>
</sect3>

<sect3><title>Evaluating a Curve</title>
<para>
To form the &Bez; curve, the collection of keys is sorted by the <varname>pos</varname> field. This should
create a strictly increasing sequence of key points, all of which are passed through by the curve. Each segment
of the curve (between two key points) needs two additional <emphasis>control points</emphasis> to be able to
be evaluated as a &Bez; curve.
</para>
<para>
The following figure illustrates a part of a one-dimensional curve, showing three adjacent keys:
<figure id='curve' pgwide='0'>
 <title>Keys in a Curve</title>
 <mediaobject>
  <imageobject>
   <imagedata fileref='media/curve/curve.png' format='PNG'/>
  </imageobject>
 </mediaobject>
</figure>
The middle key, labeled <symbol>p1</symbol>, has its two wings (the short dashed lines ending in smaller filled
circles) shown. The first and last keys have only one wing each shown, to make the figure a little bit less
complex. This is merely an omission from the figure, there is no way to actually omit wings for a key point in
the Verse data model.
</para>
<para>
The wings are not immediately defined in the same coordinate space as the curve itself. The X component of a wing
is given as a <type>uint32</type> integer, and although the Y component is a <type>real64</type> just as the curve
point, it is not immediately compatible. To go from this specialized representation to coordinates in the key point
system, a few simple computations are needed.
</para>
<para>
The position part of a wing should be interpreted as a fraction between 0 and 1, encoded as a 32-bit unsigned
integer where 0 represents 0 and <literal>0xFFFFFFFF</literal> represents 1. This fraction is used to scale the
distance to the previous or next key, and the resulting value is subtracted (for the prev-wing) or added
(for the post-wing) to the key's position to end up with the actual control point coordinate.
</para>
<para>
Once the control point's X coordinate is known from the above computation, the value-deltas can be used to
compute the Y coordinate by multiplying with the same scaled distance as used for the X component, and then
adding (or subtracting) it to the key's Y coordinate.
</para>
<para>
So, to summarize, the prev-control point is computed like this:
<itemizedlist>
<listitem>
<para>Let <varname>d</varname> be the (negative) distance from this key to the previous, in the X dimension.</para>
</listitem>
<listitem>
<para>Let <varname>p</varname> be the fraction from the prev_pos field, i.e. the value of the prev_pos field divided
by <literal>0xFFFFFFFF</literal>. This is in the range [0,1].</para>
</listitem>
<listitem>
<para>The control point is then (<varname>pos</varname> + <varname>d</varname> * <varname>p</varname>,
      <varname>value</varname> + <varname>d</varname> * <varname>prev_value</varname>).</para>
</listitem>
</itemizedlist>
The post-control point is computed in a similar fashion but with <varname>d</varname> positive. Once this has been done,
we have the four points needed to compute a single &Bez; curve segment: the curve from e.g. p<subscript>1</subscript>
to p<subscript>2</subscript> uses p<subscript>1</subscript> as its
starting position, p<subscript>2</subscript> as its end, and uses p<subscript>1</subscript>'s post-point and
p<subscript>2</subscript>'s prev-point as its two control points.
</para>
<para>
The relative way in which the control points are defined, using the wings, guarantees that the curve reacts nicely
to having new keys inserted between existing ones, and that the two wings can never be on the wrong side of their
parent key point. It is not possible to construct a curve with an <quote>S-shape</quote> using this system, which
keeps the curves well-defined for all X-values.
</para>
<para>
The above computations are simply repeated for all the dimensions of the curve.
</para>
</sect3>

<sect3>
<title>Edges</title>
<para>
The curve needs to extend to infinity in both directions, although there of course cannot be that many keys.
It also needs to be well-defined even if there is only a single key, which is not (according to the evaluation
rules above) enough to form &Bez; curves.
</para>
<para>
The way this is resolved, is to simply introduce two implicit keys in all curves: one at a X distance of 1 to
the left of the first key, and one at a X distance of 1 to the right of the last one. The constant 1 was chosen
because in general the X dimension of curves is time, expressed in seconds, and for many movements one second
is a reasonable amount of time.
</para>
<para>
The curve is linear to the left of the first key, using that key's pre-wing to define the angle, and then linear
again to the right of the last key, using it's post-wing.
</para>
</sect3>

<sect3>
<title>Using Curves</title>
<para>
How curves are connected to the rest of the data model for actual use is a bit of a research issue at the
moment; we have some ideas that will appear in the spec and implementation soon.
</para>
</sect3>
</sect2>
</sect1>

<sect1 id="n-audio">
<title>The Audio Node</title>
<para>
The audio node adds the possibility to work with digital audio in Verse applications. Audio in Verse is
represented as raw, uncompressed, pulse-code modulated (PCM) samples. This simply means that audio is
described by providing a linear sequence of amplitude values, called <emphasis>samples</emphasis>, and a
desired replay <emphasis>frequency</emphasis>. This way of describing audio digitally is fairly standardized
and well supported by typical hardware.
<note><title>Terminology</title><para>The word <emphasis>sample</emphasis> is used to denote a single
numerical value in a PCM sequence; it is not used to refer to the whole sound.</para>
</note>
</para>
<para>
Verse audio is always monaural, a single sound cannot be in stereo. This better mimics the properties
of real-world audio sources, which are considered to be points in space from which audio is emitted. It
is up to whatever software is used to <quote>render</quote>, i.e. play, the audio to create different
versions for a human listener's left and right ears, if so desired.
</para>
<para>
Audio, in both buffers and streams, is represented as uncompressed PCM (pulse-code modulation) data, meaning
linear sequences of digital values that represent the audio amplitude at some point in time. The two main
parameters that control the quality of the sound then become the sampling frequency, i.e. how many such values
exist per unit of time, and the sampling resolution, i.e. how many bits are used to represent the value. Verse
supports arbitrary sampling frequencies, and a six different sample formats of both fixed-point (integer) and
floating-point varieties.
</para>
<sect2>
<title>Audio Data Organization</title>
<para>
Verse supports samples in the following formats:
<informaltable>
<tgroup cols='2'>
<thead>
<row><entry>Format</entry><entry>Description</entry></row>
</thead>
<tbody>
<row><entry>VN_A_BLOCK_INT8</entry><entry>8-bit signed integers. The most space-efficient format supported,
but not a very high-quality one.</entry></row>
<row><entry>VN_A_BLOCK_INT16</entry><entry>16-bit signed integers. Perhaps the format that is most commonly
used in low to medium-end audio applications, such as typical games on PCs and consoles.</entry></row>
<row><entry>VN_A_BLOCK_INT24</entry><entry>24-bit signed integers. Since most general-purpose CPUs don't have
a native 24-bit integer data type, these are represented as three unsigned 8-bit bytes, stored in big-endian
order without any padding.</entry></row>
<row><entry>VN_A_BLOCK_INT32</entry><entry>32-bit signed integers, for added precision.</entry></row>
<row><entry>VN_A_BLOCK_REAL32</entry><entry>32-bit floating point numbers, stored in IEEE-754 big-endian
format. For high-end processing applications.</entry></row>
<row><entry>VN_A_BLOCK_REAL64</entry><entry>64-bit floating point numbers, stored in IEEE-754 big-endian
format. For very high-end processing applications.</entry></row>
</tbody>
</tgroup>
</informaltable>
Verse does not support unsigned samples, and neither does it support the compression of audio data.
</para>
<para>
Samples are always transmitted and received collected into <emphasis>blocks</emphasis>; it is not possible
to send a single sample value. This coarser granularity helps reduce the overhead of transmitting bulk data
such as audio. The number of samples in a single block depends on the chosen sample format, according to the
following table:
<informaltable>
<tgroup cols='2'>
<thead>
<row><entry>Format</entry><entry>Block Size</entry></row>
</thead>
<tbody>
<row><entry><symbol>VN_A_BLOCK_INT8</symbol></entry><entry>1024</entry></row>
<row><entry><symbol>VN_A_BLOCK_INT16</symbol></entry><entry>512</entry></row>
<row><entry><symbol>VN_A_BLOCK_INT24</symbol></entry><entry>384</entry></row>
<row><entry><symbol>VN_A_BLOCK_INT32</symbol></entry><entry>256</entry></row>
<row><entry><symbol>VN_A_BLOCK_REAL32</symbol></entry><entry>256</entry></row>
<row><entry><symbol>VN_A_BLOCK_REAL64</symbol></entry><entry>128</entry></row>
</tbody>
</tgroup>
</informaltable>
These numbers have been chosen to optimize packet sizes for the network transmission of audio. There is
no way to send a partially full packet; you must always provide (and expect) the number of samples that
corresponds to the layer type. Pad with zeroes towards the end to create silence, if needed.
</para>
<para>
The sampling frequency associated with audio data is specified using a 64-bit floating point number,
and is expressed in Hertz (Hz). So, for CD-quality audio, you would use a VN_A_BLOCK_INT16-type layer
at a frequency of 44,100.0 Hz.
</para>
</sect2>
<sect2>
<title>Node Structure</title><para>
The audio node provides two distinct kinds of support for handling audio data:
<itemizedlist>
<listitem><para>Buffers, that store but cannot play audio samples.</para></listitem>
<listitem><para>Streams, that play but cannot efficiently store audio samples.</para></listitem>
</itemizedlist>
These two variants of support complement each other, and make the overall audio support richer
than having just one would. The buffer and stream mechanisms are described in more detail below.
</para>
<para>
Because the number of samples per block varies with the block's type, and the duration of playback
of a single sample varies with the frequency (as 1:1, i.e. at N Hz, you need N samples per second),
it is not possible to specify the duration of playback of a single block of audio.
</para>
<sect3>
<title>Buffers</title>
<para>
Buffers, like in the text node node, are used to store audio data for editing. A buffer is simply a named
container that can hold blocks of samples. Each such block is given an index, simply an integer that
tells you the location of the block in the buffer as a whole. There can be gaps in the index sequence,
that represent silence.
</para>
<para>
The intended use for audio buffers is creating audio editing applications; they provide a host-side
<quote>back end</quote> for audio storage. By storing the samples as blocks of the same size used
by streams (see below), the transition from passive storage to active playback can be made easier.
</para>
<para>
The following image (<xref linkend='audioblocks'/>) illustrates how buffer blocks form a sequence,
and that there can be gaps where the data is <quote>clear</quote>, i.e. the amplitude is zero and
the audio silent. The vertical lines at regular intervals illustrate block boundaries (these blocks
are 128 samples each), and the digits below are the block indices of each. Note how they start off at
zero, and how the index of the silent block is still a valid index.
<figure id='audioblocks'>
<title>Audio Buffer Blocks</title>
<mediaobject>
<imageobject>
<imagedata fileref='media/audio/buffer.png'/>
</imageobject>
</mediaobject>
</figure>
</para>
<sidebar>
<title>API Links</title>
<para>
Audio buffers are manipulated using the <xref linkend='verse_send_a_buffer_create'/>,
<xref linkend='verse_send_a_buffer_destroy'/>, <xref linkend='verse_send_a_buffer_subscribe'/>
and <xref linkend='verse_send_a_buffer_unsubscribe'/> functions. Data for buffers is set using
the <xref linkend='verse_send_a_block_set'/> and <xref linkend='verse_send_a_block_clear'/> functions.
</para>
</sidebar>
</sect3>

<sect3>
<title>Streams</title>
<para>
Streams are simply independent <quote>places</quote> where audio data can be sent for playback. It might be
helpful to think of them as channels of a <quote>radio</quote> (the node), each of which can be subscribed
to individually.
</para>
<para>
Unlike almost all other data in Verse, stream data is transferred in an unreliable way; any dropped
audio commands will not be resent. This is because the intent is for the commands to contain data
to be replayed imminently, there should not be enough time to do a resend.
</para>
<para>
Data in streams arrives in time-stamped blocks, one per command. The size of the blocks, in number of
samples, varies with the data type chosen as per the table above. For network data encoding/decoding
reasons, each block specifies its data type and sample frequency, although it is not recommended that
these are actually varied in the same stream as that creates rather complex problems during replay.
</para>
<para>
The timestamp in each block lets the receiver know when that block is supposed to start playing. A typical
stream playing client will put the block in a queue, sorted on the timestamp. Blocks are then de-queued
and played, possibly employing some kind of double buffering scheme, as the current time reaches that of
the block's timestamp.
</para>
<sidebar>
<title>API Links</title>
<para>
Audio streams are manipulated using the <xref linkend='verse_send_a_stream_create'/>,
<xref linkend='verse_send_a_stream_destroy'/>,
<xref linkend='verse_send_a_stream_subscribe'/> and
<xref linkend='verse_send_a_stream_unsubscribe'/> functions. Data is sent across the stream using the <xref linkend='verse_send_a_stream'/> function.
</para>
</sidebar>
</sect3>
</sect2>

</sect1>

<sect1 id='subscription-graphs'>
<title>Subscription Graphs</title>
<para>
Data in Verse is accessed through <link linkend="subscription">subscription</link>. The data is arranged
hierarchically, so that a client needs to subscribe to increasingly more specialized <quote>areas</quote>
to reach it. The following sections describe these areas, for data that is available in all nodes (name,
tags) and for node type-specific data.
</para>
<sect2>
<title>Common Data</title>
<para>
The following figure represents the top-level common node data, that is available in all nodes:
<figure>
<title>Common Data Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-node.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
In this graph, a node (ellipse) represents a state a client can be in, with respect to what data it subscribes to.
The nodes are labeled with the names of the commands that it can receive in that state. Edges (labeled arrows)
represent commands sent by the client to the host, to request to subscribe to more (or less) data and thus change
the state. The list below describes each of the states for common node data:
</para>
<orderedlist>
<listitem>
<para>
The initial status, symbolized by the upper-most node labeled <quote>None</quote> is that the client knows
nothing about the available nodes. By sending a <xref linkend='node_index_subscribe'/> command, the client can
request information about available nodes of a set of types (expressed as a mask, M). This request is a kind of
subscription, too, as the host must remember the mask and act according to it until it is changed. However, note
that there is no corresponding unsubscribe command; instead use a different mask value to request that information
no longer is sent.
</para>
</listitem>
<listitem>
<para>
Assuming nodes of the specified type(s) exist, the client will end up in a state where it receives the
<xref linkend='node_create'/> (and <xref linkend='node_destroy'/>) commands, providing it with information
about the existing nodes. 
</para>
</listitem>
<listitem>
<para>
By sending a <xref linkend='node_subscribe'/> command, the client can start subscribing to a node, which will then
move its state to the next node (marked with a double border). There, it will learn about the node's name and its
tag groups (if any). To find out about the contents of a tag group, it needs to use the
<xref linkend='tag_group_subscribe'/> command to request a subscription to it.
</para>
</listitem>
<listitem>
<para>
The final (bottom-most) node represents the state where a client has asked to subscribe to a tag group, and the
host will then send commands to describe its contents, i.e. the value of each tag in it.
</para>
</listitem>
</orderedlist>
<para>
Each client has a <quote>position</quote> in the above graph for each node it has learned about; it is perfectly
possible to subscribe to all tag groups of a single node while ignoring them completely for ten other.
</para>
</sect2>

<sect2>
<title>Object Node</title>
<para>
This graph begins with a double-bordered ellipse. This ties together with the double-bordered ellipse in the
previous graph, the one showing common node data. The two states are logically the same, but this graph shows
what can happen in the special case where the node is known to be an object node.
<figure>
<title>Object Node Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-o.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<orderedlist>
<listitem>
<para>
Objects have <link linkend='obj-light'>light</link> and <link linkend='obj-link'>link</link> support, and the
information that describing it is sent to all object node subscribers. Also sent is information about available
method groups. There is a <link linkend='obj-transform'>transform</link>, too, which can be subscribed to although
no information about its existence is sent to node-level subscribers; it is always there so it is implicit.
</para>
</listitem>
<listitem>
<para>
Sending the <xref linkend='o_transform_subscribe'/> command switches to the bottom left state, and causes the
host to start sending updates to the object's transform.
</para>
</listitem>
<listitem>
<para>
Sending the <xref linkend='o_method_group_subscribe'/> command switches to the bottom right state, and causes the
host to start sending updates to the method group(s) in question.
</para>
</listitem>
</orderedlist>
<para>
It is important to realize that a client can be in both the bottom left and bottom right states at the same time,
by simply subscribing to both the transform and to one or more method groups. The <quote>states</quote> are not
mutually exclusive.
</para>
</sect2>

<sect2>
<title>Geometry Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common node data figure,
but this graph also shows what can happen when the node is known to be a geometry node.
<figure>
<title>Geometry Node Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-g.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
The geometry node, although one of the most data-rich nodes in Verse, has a rather shallow subscription space.
Once subscribed to a geometry node, a client will learn about the existing layers, and also get the definitions
of any bones defined in the node. Crease information is also sent to all subscribers. To get the geometry data,
a client needs to subscribe to the desired layer using <xref linkend='g_layer_subscribe'/>. Doing so forces the
client to chose a desired precision for any floating-point numbers in the layers.
</para>
<para>
Once subscribed to a layer, the client receives the layer's contents and any changes done for as long as it is
subscribed. Vertex data is delivered using ether <xref linkend='g_vertex_set_xyz_real32'/> or
<xref linkend='g_vertex_set_xyz_real64'/> depending on the requested precision. Polygon data is delivered using
one of the g_polygon_set commands, depending on the layer type. The command names indicated in the lower ellipse
in the graph above are simplified; they should be read as ending with the proper suffix depending on the type
of the layer. For instance, for a VN_G_LAYER_VERTEX_REAL layer, the actual command in question is either
<xref linkend='g_vertex_set_real32'/> or <xref linkend='g_vertex_set_real64'/> depending on the precision at
which the client is operating.
</para>
<para>
Any client that is subscribed to the base layers for vertices and polygons (layers 0 and 1, respectively) will
also receive the g_vertex_delete and g_polygon_delete commands, when deletions occur. This distinction is not
visualized in the above graph.
</para>
</sect2>

<sect2>
<title>Material Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common node data figure,
but this graph also shows what can happen when the node is known to be a material node.
<figure>
<title>Material Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-m.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
The material node contains no areas to which clients can subscribe, so this graph is very small. Just subscribing
to a material node is enough to learn about all the fragments in it.
</para>
</sect2>

<sect2>
<title>Bitmap Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common node data figure,
but this graph also shows what can happen when the node is known to be a bitmap node.
<figure>
<title>Bitmap Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-b.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
The bitmap node's data is fairly simple in its organization. All subscribers to a bitmap node will learn about
its dimensions, and about available layers. To get at actual pixels, one needs to subscribe to the desired layer.
</para>
<para>
Having subscribed to a layer, its contents will be delivered (and kept up to date) by the host through the use of
the <xref linkend='b_tile_set'/> command.
</para>
</sect2>

<sect2>
<title>Text Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common node data figure,
but this graph also shows what can happen when the node is known to be a text node.
<figure>
<title>Text Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-t.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
The text node's data is arranged into buffers. When first subscribing to the node, a client will learn about the
language of the node's contents, and about the available buffers. To learn about a buffer, a client needs to send
the <xref linkend='t_buffer_subscribe'/> command.
</para>
<para>
Once subscribed to a buffer, a client will learn about its contents through receiving the
<xref linkend='t_text_set'/> command, as shown in the lower part of the figure.
</para>
</sect2>

<sect2>
<title>Curve Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common node data figure,
but this graph also shows what can happen when the node is known to be a curve node.
<figure>
<title>Curve Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-c.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
The curve node's data is arranged into <emphasis>curves</emphasis>, each of which can be subscribed to as
a unit. When first subscribed to a curve node, a client will receive information about existing curves.
It can then choose to subscribe to a curve, by sending the <xref linkend='c_curve_subscribe'/> command.
</para>
<para>
Once subscribed to a curve, a client receives a copy of its contents (which continue to arrive if the contents
change) through the <xref linkend='c_key_set'/> and <xref linkend='c_key_destroy'/> commands.
</para>
</sect2>

<sect2>
<title>Audio Node</title>
<para>
The double-bordered ellipse here is logically the same as the one in the common data figure,
but this graph adds the audio-specific commands.
<figure>
<title>Audio Subscription Graph</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="media/subscription-a.png" format="PNG"/>
 </imageobject>
</mediaobject>
</figure>
</para>
<para>
Audio data is arranged into <emphasis>buffers</emphasis> and <emphasis>streams</emphasis>, each of which can
be subscribed to using either the <xref linkend='a_buffer_subscribe'/> or the <xref linkend='a_stream_subscribe'/>
command, respectively. If subscribed to a buffer, a client will receive any data sent out to it, through the
<xref linkend='a_block_set'/> command. Data sent to a stream will arrive through the <xref linkend='a_stream'/> command.
</para>
<para>
As with any node that has multiple subscribable entities, it is important to realize that a client can be in both
the bottom left and bottom right states at the same time, by simply subscribing to both one or more buffers and to
one or more streams. The <quote>states</quote> are not mutually exclusive, here.
</para>
</sect2>

</sect1>

</chapter>

<chapter id="protocol">
<title>Network Protocol</title>

<sect1>
<title>Introduction</title>
<para>
This chapter describes the Verse network protocol. The purpose of the protocol is to make the
<link linkend='datamodel'>data model</link> available over a computer network. This is central to the Verse fundamental
idea, to make 3D graphics and audio data into something that can be shared by different applications over a network.
</para>
<para>
The description is arranged in a bottom-up manner, beginning by talking about how how data is abstractly
represented as various <link linkend='protocol-datatypes'>data types</link>, that are given concrete external
representations through <link linkend="protocol-encoding">encoding</link>. Encoded data is then arranged into
<link linkend="protocol-commands">commands</link>, which are finally turned into
<link linkend="protocol-packets">packets</link> for transmission.
</para>
</sect1>

&Types;

<sect1 id="protocol-encoding">
<title>Data Encoding</title>
<para>
The purpose of the network protocol is to allow data to be serialized and transmitted over a network in a
way that is independent of the machine type of the transmitting end. This requires well-defined ways to represent
various kinds of values, and how this is done is specified in this section. The discussion is split into sections
for each major type of value required by Verse;
<link linkend="protocol-encoding-ints">integers</link>,
<link linkend="protocol-encoding-reals">reals</link> (floating-point numbers),
<link linkend="protocol-encoding-strings">text strings</link>,
<link linkend="protocol-encoding-enums">enumerations</link>,
and
<link linkend="protocol-encoding-structs">structures</link>. There is also a description of how
<link linkend="protocol-encoding-arrays">arrays</link> of these value types are encoded.
</para>
<para>
Being external representations, all numerical types have well-defined sizes, in bits.
</para>

<sect2 id="protocol-encoding-ints">
<title>Integers</title>
<para>
All the various integers <link linkend='ints'>defined in Verse</link> are encoded as sequences of 8-bit
bytes, with the number of bytes trivially deductible from the bit-size of the integer type (simply divide
by eight). Encoding is done in <quote>network byte order</quote>, with the most significant byte first
(towards the start of a packet).
</para>
<!--
<para>
The exception is the <link linkend='type-uint1'>1-bit unsigned integer type</link>; since it is smaller
than one byte, the previous paragraph does not hold. Luckily, uint1s only occur in one place, and that's as an
array of length 16 which is simply represented as two bytes.
</para>
-->
<para>
Signed integers are encoded in two's complement form, with the most significant bit being the sign bit.
</para>
<para>
The various <link linkend='intaliases'>integer aliases</link> encode as the types they alias, respectively.
</para>
</sect2>

<sect2 id='protocol-encoding-reals'>
<title>Reals</title>
<para>
Reals are encoded as <ulink url='http://grouper.ieee.org/groups/754/'>IEEE 754</ulink> numbers, and occupy
four or eight bytes each depending on precision. The first byte in the encoded form holds the sign bit in its most significant bit,
followed by the biased exponent and finally the mantissa.
The general form for real numbers is thus:
<informaltable align='center'>
<tgroup cols='3'>
<thead>
<row>
 <entry align='center'>Type</entry>
 <entry align='center'>Sign Bit</entry>
 <entry align='center'>Exponent</entry>
 <entry align='center'>Mantissa</entry>
</row>
</thead>
<tbody>
<row>
 <entry><type>real32</type></entry>
 <entry align='center'>1</entry>
 <entry align='center'>8</entry>
 <entry align='center'>23</entry>
</row>
<row>
 <entry><type>real64</type></entry>
 <entry align='center'>1</entry>
 <entry align='center'>11</entry>
 <entry align='center'>52</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</sect2>

<sect2 id='protocol-encoding-strings'>
<title>Strings</title>
<para>
<link linkend='strings'>Strings</link> are encoded in <ulink url='http://www.utf-8.com/'>UTF-8</ulink>. Briefly, this means that characters
with Unicode code points <literal>U+0001</literal> to <literal>U+007f</literal> (inclusive) are encoded as single
bytes with the value of the code point, while code points outside that range require multiple bytes. At most, a
single character requires four bytes to encode.
</para>
<para>
Strings use a byte with the value <literal>0</literal> to mark the end, so no string can contain that byte
legally. An empty string is thus encoded as a single byte with the value <literal>0</literal>.
</para>
</sect2>

<sect2 id='protocol-encoding-enums'>
<title>Enumerations</title>
<para>
All <link linkend='enums'>enumerations</link> encode as the <link linkend='type-uint8'><type>uint8</type></link>
integer type, and thus have had all their values chosen to fit in the numerical range of that type.
</para>
</sect2>

<sect2 id='protocol-encoding-arrays'>
<title>Arrays</title>
<para>
Arrays are encoded simply as a sequence of values of the basic type, one after the other, and with no extraneous
information about number of elements as part of the actual array. For variable-length arrays, the length must be
encoded in some preceding field to allow proper decoding, as the length is not encoded automatically as part of
the array.
</para>
<para>
For arrays of unions, it must be specified where the information needed to resolve which union member is present
is stored, and if it is shared by all slots or not. This is unlike programming languages such as C and C++, where
unions always occupy enough space to accommodate their largest possible member.
</para>
</sect2>

<sect2 id='protocol-encoding-structs'>
<title>Structures and Unions</title>
<para>
A <link linkend='structs'>structure</link> is encoded by encoding its fields, in order as they appear in the
definitions, end-to-end. There is no padding between fields.
</para>
<para>
A union type is encoded by picking one of the fields, using external information, and then applying whatever
encoding rules apply to that field's type. The encoded size of a union is exactly the size of whichever
field was encoded, there is no padding of the union as a whole to the size of the largest field (unlike the
in-memory representation of unions in the C language).
</para>
</sect2>

<sect2>
<title>Alignment</title>
<para>
Verse data is always encoded completely <emphasis>without padding</emphasis> after or between values. Since all
commands begin with the command byte, this means that the rest of the fields are almost guaranteed
<emphasis>not</emphasis> to be aligned in any particular manner. Thus, code that deals with doing encoding
and decoding must be carefully written.
</para>
<para>
Basically, accessing the command buffers on a byte-by-byte basis is the easiest way to do this safely. Doing whole
reads and writes of data types bigger than one byte (such as a <type>double</type> which is generally the way the
<type>real64</type> data type is implemented in C) using non-aligned addresses can often cause bad performance,
or even crashes.
</para>
<para>
The reference API implementation hides these details from users; application programmers using it need never concern
themselves with how Verse data is transported in a network.
</para>
<para>
No data type is smaller than a single byte; Verse data is encoded as a sequence of whole bytes with no overlap,
all bits of a given byte always belong to the same logical field.
</para>
</sect2>

<sect2><title>Examples</title>
<para>
Here are few simple examples of how values of the various types encode in the network. Encoded data is shown
as a sequence of bytes, where the leftmost byte would be the one towards the beginning of the packet.
</para>

<example>
<title>A signed integer</title>
<para>The integer <literal>-4711</literal>, taken as an <link linkend='type-int32'><type>int32</type></link>,
would be encoded like this:
<informaltable>
<tgroup cols='4' align='center'>
<tbody>
<row>
<entry><literal>0xff</literal></entry>
<entry><literal>0xff</literal></entry>
<entry><literal>0xed</literal></entry>
<entry><literal>0x99</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</example>

<example>
<title>An unsigned integer</title>
<para>The integer <literal>711</literal>, taken as an <link linkend='type-uint16'><type>uint16</type></link>,
would be encoded like this:
<informaltable>
<tgroup cols='2' align='center'>
<tbody>
<row>
<entry><literal>0x02</literal></entry>
<entry><literal>0xc7</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</example>

<example>
<title>A Simple String</title>
<para>
The 10-character string <quote>Verse test</quote> would encode as the following sequence of eleven 8-bit bytes:
<informaltable>
<tgroup cols='11' align='center'>
<tbody>
<row>
<entry><literal>0x56</literal></entry> <!-- V -->
<entry><literal>0x65</literal></entry> <!-- e -->
<entry><literal>0x72</literal></entry> <!-- r -->
<entry><literal>0x73</literal></entry> <!-- s -->
<entry><literal>0x65</literal></entry> <!-- e -->
<entry><literal>0x20</literal></entry> <!-- SPC -->
<entry><literal>0x74</literal></entry> <!-- t -->
<entry><literal>0x65</literal></entry> <!-- e -->
<entry><literal>0x73</literal></entry> <!-- s -->
<entry><literal>0x74</literal></entry> <!-- t -->
<entry><literal>0x00</literal></entry> <!-- NUL -->
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</example>

<example>
<title>An International String</title>
<para>The 7-character string <quote><foreignphrase>smörgås</foreignphrase></quote>
<footnote><para>Swedish for <quote>sandwich</quote></para></footnote>
encodes as the following 10-byte sequence using UTF-8:
<informaltable>
<tgroup cols='8'>
<tbody>
<row>
<entry><literal>0x73</literal></entry>  <!-- s -->
<entry><literal>0x6d</literal></entry>  <!-- m -->
<entry><literal>0xc3</literal></entry>  <!-- ö -->
 <entry><literal>0xb6</literal></entry> <!-- ö part 2-->
<entry><literal>0x72</literal></entry>  <!-- r -->
<entry><literal>0x67</literal></entry>  <!-- g -->
<entry><literal>0xc3</literal></entry>  <!-- å -->
 <entry><literal>0xa5</literal></entry> <!-- å part 2-->
<entry><literal>0x73</literal></entry>  <!-- s -->
<entry><literal>0x00</literal></entry>  <!-- NUL -->
</row>
</tbody>
</tgroup>
</informaltable>
Here, it is clear that a string using characters outside the range <literal>U+0001</literal> to <literal>U+007f</literal>
inclusive will use more space in their encoded form than a string that uses only characters from inside the range.
</para>
</example>
</sect2>

</sect1>

<sect1 id="protocol-commands">
<title>Node Commands</title>
<para>
A <emphasis>command</emphasis> is the unit of communication using Verse. Commands are sent between client and
host and express either global actions affecting the session as a whole, or address individual nodes directly.
</para>
<para>
The set of available commands is strictly defined in this specification, and Verse-compliant applications
cannot go outside it. This is because a goal with Verse is interoperability, and the set of commands needs to
be shared by all applications for this to be achieved. There are about 60 unique commands defined in this
specification.
</para>

<sect2>
<title>Structure</title>
<para>
The structure of a Verse network command is simple: a command is a finite sequence of bits. This sequence
consists of individual <emphasis>fields</emphasis> of varying length. A field is typically a value in one of
the supported network data formats and encoded according to the <link linkend="protocol-encoding">encoding standard</link>.
The first field has a fixed length of 8 bits, and always holds an integer value that identifies the command.
This field is called the <emphasis>command ID</emphasis> (or command byte) and completely determines the format
of the subsequent bits. The following bytes make up the command's <emphasis>parameters</emphasis>, which are
very much analogous to parameters in ordinary function calls.
</para>
<para>
The value of the initial command byte completely determines the exact format of the following bits, and also
how many bits are present. The size of a command need not be constant, however; there are both variable-length
single parameters (zero-terminated character strings) and parameters whose presence is determined by the
value of previous parameters in the same command.
</para>
<sect3>
<title>System vs. Node Commands</title>
<para>
There are two major categories of commands: system commands, and node commands. The defining difference
here is that system commands are not not sent to any specific node, they alter the session as a whole.
Node commands, on the other hand, are always sent to exactly one node. With this difference in mind, we
can present the following two schematic views of command structure:
<informaltable pgwide="1" frame="all">
<tgroup cols="3">
<tbody>
<row>
 <entry align="center"><para>
  <table frame="top">
   <title>A System Command</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>Field:</entry><entry>ID</entry><entry>parameters</entry>
     </row>
     <row>
      <entry>Width:</entry><entry align="center">8</entry><entry align="center">variable</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </para></entry>
 <entry align="center"><para>
  <table>
   <title>A Node Command</title>
   <tgroup cols="4">
    <tbody>
     <row>
      <entry>Field:</entry><entry>ID</entry><entry>Node ID</entry><entry>parameters</entry>
     </row>
     <row>
      <entry>Width:</entry><entry align="center">8</entry><entry align="center">32</entry><entry align="center">variable</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </para></entry>
</row>
</tbody>
</tgroup> 
</informaltable>
</para>
<para>
As can be seen, node commands differ from system commands by always including a 32-bit ID of the target node
as the first field following the command ID.
</para>
</sect3>
<sect3 id='cmd-addressing'>
<title>Addressing</title>
<para>
Many commands need to uniquely specify what data it reads or writes. This is done by concatenating a sequence of fields
in the encoded command, to form the <emphasis>address</emphasis>. For system commands, the command byte itself is
sometimes enough, and no further address fields are defined. For node commands, the address is extended to always
include the node ID field, and often further fields that address parts of the node.
</para>
<example id="ex-v-set-real32-addr">
<title><symbol>g_vertex_set_xyz_real32</symbol> Addressing</title>
<para>
As an example, consider setting the (X,Y,Z) position of a <link linkend="n-geometry">geometry node</link> base
layer vertex. One command that does this is
<link linkend='g_vertex_set_xyz_real32'><symbol>g_vertex_set_xyz_real32</symbol></link>,
which has a command ID value of <literal>50</literal>. This command requires three pieces of information that
together identify the vertex whose position is to be set: the node ID of the target node, the layer ID of the
layer holding the vertex, and finally the vertex ID that is the index of the vertex inside the layer. These three
values together make up the address part of the command.
</para>
<para>
In this case, we end up with a final address of (node ID, layer ID, vertex ID). Since the node ID is always 32
bits, and the layer and vertex IDs are 16 and 32 respectively, the address size is 32 + 16 + 32 = 80 bits.
</para>
</example>
</sect3>
<sect3>
<title>Content</title>
<para>
The rest of the parameters for a command make up the actual data payload, and little can be said about it in
general; the specific format is very much up to each command.
</para>
<example>
<title><symbol>g_vertex_set_xyz_real32</symbol> Content</title>
<para>
To continue from the previous example, the content used to set a vertex with 32-bit precision is simply
three <type>real32</type> values, named <varname>x</varname>, <varname>y</varname> and <varname>z</varname>
respectively. These add 3 * 32 = 96 bits to the command's parameter block, bringing the total size of the
command up to 8 + (32 + 16 + 32) + (3 * 32) = 184 bits, or 23 bytes.
</para>
</example>
</sect3>
</sect2>
<sect2 id='command-symmetry'>
<title>Command Symmetry</title>
<para>The way commands are actually used to convey information is interesting, and needs to be described
explicitly since it is perhaps not totally intuitive to everyone.
</para>
<para>
Verse node commands are very much like remote procedure calls; one end of a point-to-point network
connection can tell the other end to do something, like create a node. What makes them interesting is
the way in which the result of the operation is made known to the sender: typically, this is done by
<emphasis>sending the same command in the other direction</emphasis>, sometimes with a few values filled
in that were left blank originally.
</para>
<para>
This means that if a client sends a command to a host, asking it to e.g. move a vertex to a new position in
3D space (using the <command><link linkend='g_vertex_set_xyz_real32'>g_vertex_set_xyz_real32</link></command>
command), the following will happen:
<footnote>
<para>This example does not include sufficient detail to describe what happens if one or more commands are
lost in transit, which is always a possibility. But since packet-loss should be handled in a well-defined
manner, it can be ignored here.</para>
</footnote>
<orderedlist>
<listitem><para>The Verse network layer on the host receives the command, and notifies
<footnote><para>
In the standard API defined in this document, this notification is through the invocation of a
<emphasis><link linkend='api-callbacks'>callback function</link></emphasis>.
</para></footnote>
the host application.</para>
</listitem>
<listitem><para>
The host code validates the command, making sure it addresses a valid vertex, and that the sending client
has the right to execute the command. If it doesn't, processing ends here.
</para></listitem>
<listitem><para>
The host executes the command, typically by updating the state of the vertex layer with the new position.
</para></listitem>
<listitem><para>
The change must be distributed to all subscribers, probably also including the client that originally sent
the change. This is done by having the host construct a suitable command (for this example, this would be
the exact same command, i.e. a <command><link linkend='g_vertex_set_xyz_real32'>g_vertex_set_xyz_real32</link></command>),
and sending it out to all known subscribers.
</para></listitem>
<listitem><para>
The originating client's Verse network layer receives the update command, decodes it, and notifies the
application layer.
</para></listitem>
</orderedlist>
The point here is that the same sequence of bits (the command) is used both as a request from a client to
a host, to <quote>please set this object to this value</quote> and as an authoritative message in the other
direction, where the meaning is more along the lines of <quote>be advised, this object now has this value</quote>.
The distinction is subtle, but worth knowing about.
</para>
<para>
The above example is accurate, but only covers the case where there is a one-to-one correspondence between
the command received by the host and the command emitted by it in response to executing the request. Many
commands have a one-to-many relation instead; a client sends a single command, and the server responds with
a burst of many commands in return. This is common when requesting for a subscription to some data, for
example; the request is a single command, but the description of the data, which needs to be send to the
new subscriber, often requires several commands. In such cases, of course, there is no 1:1 relationship
between what gets sent by the client and what gets sent in response by the server. However, the individual
commands used to describe the data are still the same in both directions.
</para>
</sect2>
</sect1>

<sect1 id="protocol-packets">
<title>Packet Format</title>
<para>
Now that we have seen how Verse commands are formed, it is time to describe the particulars of how they
are actually transmitted over a network between machines. This involves the creation of <emphasis>packets</emphasis>
which are sent and received using UDP/IP.
</para>
<sect2>
<title>UDP/IP</title>
<para>
Verse always uses custom datagrams sent using UDP/IP as its transport mechanism. This is a core part of
this specification; you cannot just re-implement Verse to use e.g. TCP/IP and expect things to work; there
is a tight coupling between the transport mechanism and the command format (see <xref linkend="resend"/>).
Also, because Verse is designed and optimized for real-time performance, an area where TCP/IP has inherent
problems, such a re-implementation is not recommended.
</para>
<sect3>
<title>Ports</title>
<para>
The default port used by Verse is <literal>4950</literal>. This is the port a host will listen to, and also
the port a client will try to connect to if the supplied host address does not include an alternative number.
</para>
<para>
Once a client has connected to a host, it will be assigned a new port to use for further communication by the
host; in practice the default port is only used for the initial connection-establishment traffic.
</para>
</sect3>
</sect2>
<sect2>
<title>Packets</title>
<para>
Packets are built by simply encoding commands, end-to-end, and pre-pending a 32-bit header. There is no padding
between commands, and also no information in the header about which commands are contained in the packet. Since
commands do not have much of a header either, specifically they do not have a length indicator, to decode a packet
it is necessary to decode and interpret each command sequentially until the end of the packet is reached.
</para>
<para>
In order to reduce the overhead caused by the Internet Protocol's fragmentation handling, the reference implementation
of the Verse protocol will not emit packets larger than ~1,500 bytes. This limit has been chosen because it is the
maximum transferable unit (MTU) size of Ethernet, and the code simply assumes that the world is an Ethernet.
</para>
</sect2>
</sect1>

<sect1 id="resend">
<title>Resend Mechanism</title>
<para>
Each packet has a header consisting of a 32-bit packet ID. This packet ID increases with each packet sent, and makes
it possible for the receiving end to know if a particular packet has been lost during the transfer.
</para>
<para>
When an implementation notices one or more lost packets it will have to notify the other side by sending a
<emphasis>negative acknowledgment</emphasis> (<acronym>NAK</acronym>), and each packet that is successfully
received has to be confirmed by sending a <emphasis>positive acknowledgment</emphasis> (ACK).
</para>
<para>
The nak and ack commands are like any other command defined in the command specification. If a packet arrives,
all non-received commands since the last received commands are considered lost, and the implementation can immediately
decode and use the information in the arrived packet without waiting for data to be resent. If a lost packet later
arrives out of order, it should be ignored. Both sides must store history of sent data to be able to re-send any
data that may have been lost.
</para>
<para>
The NAK and ACK commands both include a single parameter; a 32-bit packet ID number. For NAK, the semantics are
that the indicated packet was lost and needs to be re-sent. The sending end must look it up in its packet history,
and re-send it. For ACK, the semantics are the inverse: the indicated packet was successfully received, and can
be removed from the history buffers.
</para>
<para>
If one side of a Verse connection fails, the other side's history buffer will eventually fill up. It is then free
to give up. Protocol implementations should provide a way for applications to determine how large the history
buffer is, so they can make the decision to terminate.
</para>
<sect2><title>Event Compression</title>
<para>
As described above, all commands sent out by a Verse application are buffered by the implementation, to be available
for resend should a NAK arrive. However, they are not simply buffered and forgotten until (possibly) re-sent. When
a command is added to the history buffer, a search is done for a command with the same <link linkend='cmd-addressing'>
address</link>. If a match is found, we know the one in the buffer has been made obsolete by the new command, and
it is thus <emphasis>replaced</emphasis> in the buffer. The comparison operation needed by the search can be implemented
in two discrete steps:
<itemizedlist>
<listitem><para>Compare the command bytes. If they differ, there can be no match.</para></listitem>
<listitem><para>Compare the address information. The address is always a contiguous sequence of bytes, and
has the same (fixed) size for all instances of a given command, so this is fairly simple.</para></listitem>
</itemizedlist>
Although the command byte and address information is always immediately adjacent in the encoded command format,
it is necessary to first inspect the command bytes to learn the size of the address information, which can vary
with each individual command.
</para>
<para>
This updating of sent commands with new data means that if a client repeatedly sends out N commands addressing the
same data (say, for instance, that it is periodically changing the color of some object), only one single command
will be stored in the history buffer. This way of automatically filtering out repeated changes to the same data,
keeping only the most recent, is called <emphasis>event compression</emphasis>.
</para>
<para>
Because of event compression, the command that is (re)sent in response to a NAK might not be the same command that
was actually lost, since it might have been replaced by a more recent command changing the same data.
</para>
</sect2>
</sect1>

<sect1 id='security'>
<title>Security</title>
<para>
Security in Verse is a complicated topic. Security concepts fit at two different levels of the system: at the network
level, to protect the data that gets sent, and at a higher level, in the form of access restrictions and similar.
</para>
<para>
For a long time, all the way back to the initial version of Verse developed at the <ulink url='http://w3.tii.se/'>Interactive
Institute</ulink> in 1999, Verse had no network security at all. The network traffic was not encrypted or protected in any way,
all data was sent in clear text.
</para>
<para>
In the more recent second version, which has been further developed during the <ulink url='http://www.uni-verse.org/'>Uni-Verse</ulink>
project, network security has been added as one of the basic requirements for the platform. 
</para>
<sect2 id='security-net'>
<title>Network Security</title>
<para>
Verse's network security aims to make the data passing on the wire harder for an attacker to read. This is done by
<ulink url='http://en.wikipedia.org/wiki/Encryption'>encrypting</ulink> the packets sent by Verse, using two distinct types of encryption:
one during connection establishment, and a different one once connected.
</para>
<para>
During connection establishment, the focus is on security. Thus, data sent then (which includes potentially
sensitive information such as the username and password of the client trying to connect) is protected using
relatively <quote>heavy</quote> encryption (<ulink url='http://en.wikipedia.org/wiki/RSA'>RSA</ulink>, currently with a key length
of just 512 bits though). The performance penalty caused by the complicated encryption/decryption algorithms is offset by the fact
that a client only connects once, and that the total number of packets exchanged using this encryption is fairly low.
</para>
<para>
Once connected, performance becomes more critical. Therefore, Verse switches to a simple and fast XOR-based encryption
algorithm for data sent when connected. The key used for the XOR encryption is created by the server during the connection
establishment, and thus protected by RSA when sent to the client. The key is indexed by the packet number, and the result (modulo
the key size) is then used as a new starting position in the key, for the packet's contents. This should make it more difficult for
an attacker to figure out the key.
</para>
</sect2>
<sect2>
<title>Access Restrictions</title>
<para>
In addition to the low-level network security, which prevents an attacker from seeing the data stream and possibly interfering
with it (or just eaves-dropping it to learn potentially sensitive information), Verse needs a higher-level security  mechanism.
It should be the responsibility of this mechanism to allow the administrator of a Verse server to implement restrictions on what
users can do on the server. For instance, it might be valuable to set up a limit, so that no user can create a geometry node with
more than N vertices or polygons, to conserve memory. Or, you might want to limit the total number of nodes a single client is
allowed to create, again to limit memory use.
</para>
<para>
Access restrictions are currently not implemented in Verse. There has been some <ulink url='http://verse.blender.org/cms/Auxiliary_Spec.711.0.html#3235'>rough
sketching</ulink>, but no full specification or code exist. It is anticipated that defining a usable model for controlling access to Verse
nodes is a quite complex and difficult problem. Suggestions welcome.
</para>
</sect2>
</sect1>

<sect1 id="command-reference">
<title>Command Reference</title>
<para>This section forms a reference document that describes every defined network command in Verse.
For each command, it's complete network representation is given, and all included parameters are
described. Also described is the command's semantics, of course.</para>

<sect2>
<title>Command Semantics</title>
<para>There are two categories of network commands: system and node commands. System commands are sent to the
host itself, and are used to manage connections, and other administrative things. Node commands are sent to
actual node instances, and are used to describe the data contents.
</para>

<sect3>
<title>On Symmetry</title>
<para>
As <link linkend='command-symmetry'>noted earlier</link>, Verse commands are used both between client and
host to request something, and then in the reply from host to client to authoritatively state something. Often
the thing that is stated, the host's response, is the exact same thing that was requested but with one or
more values filled in that only the host knows about.
</para>
<para>
The descriptive texts for the commands in the following sections are written from <emphasis>the client's
perspective</emphasis> almost always. This means that e.g. the <xref linkend='g_vertex_set_xyz_real32'/> command
is described as <quote>setting the position of the vertex</quote>, rather than <quote>informing a client
about the position of a vertex</quote>, and so on.
</para>
<para>
This distinction is sometimes subtle, and well worth remembering when reading the command descriptions.
</para>
</sect3>

<sect3>
<title>Idempotent Commands</title>
<para>
All node commands contain an absolute <quote>address</quote>, in the form of node-dependent hierarchical
ID numbers, of the data being read or written. Most such node commands can be executed in any order, which
makes the protocol as a whole fairly free of command dependencies and the associated latencies. Because
of the addressing, most commands can also be executed multiple times without any harmful side effects
except (possibly) excessive network traffic. This latter property is sometimes referred to by saying that
the commands are <emphasis>idempotent</emphasis>.
</para>
<para>
While most commands are order-independent and idempotent, some commands can not be. For these commands,
there is a special transmission mode called <quote>ordered</quote>. Ordered commands must be delivered
to the receiving application in the order sent. This introduces latency, but is the only acceptable way
to deal with certain kinds of data.
</para>
</sect3>

<sect3>
<title><quote>Create</quote> versus <quote>Set</quote></title>
<para>
One area of interest is the distinction between commands that <emphasis>create</emphasis> something,
and those that merely <emphasis>set</emphasis> something. This distinction is not very clear-cut, and
the command naming is in some cases historical or traditional.
</para>
<para>
In general, commands have <link linkend='cmd-addressing'>addresses</link>. It might make sense to just
look at the address when classifying (if such classification is even necessary) a command as a create
or a set:
<itemizedlist>
<listitem>
<para>If the address points to something that is unknown, it is a request to create a new instance
of whatever type is relevant.
</para>
</listitem>
<listitem>
<para>
If, on the other hand, the addressed item exists, it should be re-set
according to the rest of the parameters in the command.
</para>
</listitem>
</itemizedlist>
In addition, the address value <quote>all bits one</quote> is often reserved to always mean <quote>create
something new</quote>. However, it is not required that a client use this special address every time it
wants to create a new instance of something; it is fine to pick its own ID, which should be as close to
the previously last-known used one as possible, and ask the server to use that.
</para>

<para>
There are some specific cases where it might be valuable with some discussion about why the commands
have been named the way they have:
<variablelist>
<varlistentry><term><xref linkend='b_tile_set'/></term>
<listitem>
<para>
This is perhaps one of the more clear-cut command names. It is not possible to create an individual
bitmap tile; all tiles are implicitly <quote>created</quote> as soon as the bitmap's dimensions are
set (using <xref linkend='b_dimensions_set'/>).
</para>
</listitem>
</varlistentry>

<varlistentry><term><xref linkend='o_light_set'/></term>
<listitem>
<para>
Again, this is fairly clear-cut. There is no addressing involved; each object node has exactly one
<quote>slot</quote> that can be used to store light values, and this command always sets precisely
those values.
</para>
</listitem>
</varlistentry>

<varlistentry><term><xref linkend='g_vertex_set_xyz_real32'/>, <xref linkend='g_polygon_set_corner_uint32'/>, ...</term>
<listitem>
<para>
These commands (all the g_vertex_set_ and g_polygon_set variants) are perhaps a bit dubious, as they obviously
can both create and change (set) the value of a vertex (or polygon) definition. One possible way to justify the
naming is that individual vertices and polygons are not subscribable objects, they are lower-level,
<quote>second class citizens</quote> if you will. Often, the naming leans towards setting un-subscribable
objects with <quote>set</quote>, while the higher-level, subscribable, entities are set using a
<quote>create</quote>-command.
</para>
<para>
Another aspect with the geometry data is that is really meant to be stored in an array, with the <quote>id</quote>
of a vertex (or polygon) being simply its index in that array. This makes it simpler, and thus less worthy of a
<quote>create</quote> command, perhaps.
</para>
</listitem>
</varlistentry>

<varlistentry><term><xref linkend='g_bone_create'/></term>
<listitem>
<para>
This command, perhaps, is the exception that proves the rule given above. Bones are not subscribable
entities, yet they are created (or modified) by a command named <quote>create</quote>. One explanation
here might be that bones contain references to each other, for hierarchy, so the numerical identifiers
used to address them have slightly more significance than the plain indexes used with vertex and polygon data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>

<sect3>
<title>Being <quote>Done</quote></title>
<para>
Verse data transmissions can never be known to be <quote>complete</quote>, since even if your particular
client is a passive receiver only, you can never be sure that there isn't some other client connected
that is adding, editing, or deleting data.
</para>
<para>
This means clients can rarely be designed with some kind of hard separation into stages; i.e. you can't
say <quote>first I download the geometry, then I...</quote>, because there is no way of knowing when e.g.
the geometry has been <quote>fully</quote> downloaded. Indeed, the concept isn't even defined since
it can change at any moment.
</para>
<para>
This property means that any processing (for instance subdivision of geometry for rendering as triangles)
done on Verse data needs to be able to restart when data changes, and be ready to do so at any time.
</para>
</sect3>

</sect2>

</sect1>

<!-- Just include the entire protocol snippet, built separately from custom XML using XSLT. -->
&Commands;

<sect1 id="command-index"><title>Command Index</title>
<para>
Below is a table that lists all the defined commands, in numerical order. You can click a command
name to go to the definition page for that command. Aliased commands are shown with two names for
a single ID, separated by a slash.
&Command-Index;
</para>
</sect1>

</chapter>

<chapter id='api'>
<title>Standard API</title>
<sect1 id='api-intro'>
<title>Introduction</title>
<para>To simplify for Verse application programmers, there is a standard API defined here. This API, which is
written in C, is usable for implementing both Verse clients and hosts.
</para>
<sect2 id='api-goals'>
<title>API Goals</title>
<para>This section describes some of the design goals with the Verse standard API, motivates the choices,
and tells you what the API does and (sometimes more importantly) what it does not do for you, the application
programmer.
</para>
<para>
The Verse API has been designed to be basically a way to send and receive Verse commands, i.e. primarily
an implementation of the network protocol part of Verse. It does not include extensive support for the
<emphasis>data model</emphasis>, since that is considered outside its scope and can be built on top of
the API.
</para>
<para>
Thus, the API contains a function to send the command that describes e.g. a node to be created, but it does
not define any data structures or functions needed to actually represent a node according to the Verse data
model in memory. The design of the command set reflects this, and makes it possible to design as <quote>stupid</quote>
an API as possible. For instance, data format information is often repeated both in e.g. the command that
creates the data container (such as a layer) and in the command holding the data itself. This is because the command
set assumes that the API does not buffer the information on its own, so each command needs to be self-contained.
</para>
<para>
In use, the Verse API sits in between the application code and the underlying operating system. The API accepts the
application's requests to send commands, and do whatever is necessary to cause the operating system to actually emit
a properly-formed packet of data. Simultaneously, the API listens after incoming Verse packets, decodes them, and
delivers the contained data to the application.
</para>
<para>
It should be very possible to design an API that does more data buffering, perhaps of only meta information,
to hide this from the application programmer. We encourage such development.
</para>
</sect2>
<sect2>
<title>Choice of Language</title>
<para>
As stated above, the standard API is written in C, and made available as a C interface. This might be slightly
controversial, and worthy of further explanation. Of course, this topic is dangerously close to advocacy, which
is not the goal of this text. Still, below are some of the reasons why we feel C is a good choice.
<variablelist>
<varlistentry>
<term>Systems Programming</term>
<listitem><para>
The Verse API is intended to be the bottom-most layer between an application and the Verse network protocol,
and therefore it makes sense to use C, which is a traditional <quote>systems</quote> programming language.
</para></listitem>
</varlistentry>

<varlistentry>
<term>Performance</term>
<listitem><para>
Since the Verse protocol layer might easily become a bottleneck in data-intensive applications, choosing
a language where it is possible to have detailed control of performance characteristics is natural. C is
such a language.
</para></listitem>
</varlistentry>

<varlistentry>
<term>Easily Wrapped</term>
<listitem><para>
To make Verse available from other programming languages, one approach is to <quote>wrap</quote> an existing
API in whatever interface is more natural in the target language. C is easily wrapped in this way, since it
is often used to <emphasis>implement</emphasis> other (primarily higher-level) languages.
</para></listitem>
</varlistentry>

</variablelist>

</para>
</sect2>

<sect2 id='api-callbacks'>
<title>About Callbacks</title>
<para>
When a command is received, the Verse API cannot handle the situation on its own, since it is too thin
a layer; it does not know what needs to be done when e.g. a vertex is moved, or a bitmap layer is created.
The API needs to pass the information that a command was received <quote>up</quote> and into the application
code where it can be dealt with.
</para>
<para>
Such event passing can be done in several ways, but the two major ones are probably by callbacks, and
by explicitly defining event data types and allowing applications to handle events as first-class entities. The
Verse API uses callbacks, which is arguably the smaller of the two approaches in terms of requirements on the API
itself (no need to define event data structures).

</para>
<para>
The callback approach requires two things:
<itemizedlist>
<listitem><para>That it is clearly defined how the callback for a given event should look. As will become
clear later, this is met by a simple symmetry between the API's functions for sending commands and the functions
for handling notifications.</para></listitem>
<listitem><para>There must be a way for the application programmer to associate a callback with the
reception of a command. This is handled through the API's <xref linkend='verse_callback_set'/> function,
using send function pointers as keys.
</para></listitem>
</itemizedlist>
</para>
</sect2>

</sect1>

<sect1 id='api-overview'>
<title>API Overview</title>
<para>This section describes the top-level design of the API, which should make it easier to
understand. Each part is not enough to get any work done on its own; even the simplest application
must use functionality from at least two of the parts, and many typical clients will use them all.
</para>
<para>
The Verse standard API has been designed to be as easy as possible to work with, and also to be very
easy to integrate into program development. It has very few (if any) external code dependencies, and does
not rely on any libraries other than those that are included on standard operating systems (e.g. libraries
to deal with socket-level communication).
</para>
<para>
The library has a single header file, <filename>verse.h</filename>, which is included in all source code
files that wish to use the API. There is no need to initialize the API before using it, you can just go
ahead and call the desired functions right away.
</para>
<para>The API can be more or less dissected into three parts, where each parts contains functions for
solving similar problems. These parts are:
<variablelist>
 <varlistentry>
  <term><link linkend='api-ref-session'>Session Management</link></term>
  <listitem>
   <para>These are functions for working with <emphasis>sessions</emphasis>, which are connections from a
client to a host. There is also support for becoming a host here, and listen to incoming connections. Further,
there are functions for working with <emphasis>callbacks</emphasis>, which are a core part of the API.
</para>
  </listitem>
 </varlistentry>
 <varlistentry>
  <term><link linkend='api-ref-data'>Pack/Unpack Helper Functions</link></term>
  <listitem>
   <para>These are functions that help deal with complex data representations. Rather than have the
sending function (see below) do any required data conversions, it is left to an auxiliary function
in this group. This makes it possible to convert data once, then send it many times, which is necessary
for the efficient implementation of hosts (or multi-session clients).</para>
  </listitem>
 </varlistentry>
 <varlistentry>
  <term><link linkend='api-ref-commands'>Command Sending Functions</link></term>
  <listitem>
   <para>This is the largest group, by a large margin. It is basically a 1:1 mapping of
<link linkend="command-reference">commands</link> to functions, with one function to send each of the
defined commands for all node types. At the time of writing, there are roughly 90 such functions.</para>
  </listitem>
 </varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id='api-typical-client'>
<title>A Typical Client</title>
<para>Since most Verse applications are assumed to be clients, it makes sense to spend a little extra
time here to outline how a typical client would use functions from the various parts of the API.
</para>
<para>
The general client will follow the following sequence of steps (links are to the API entry points most
relevant for each step):
<itemizedlist>
 <listitem>
  <para>Create session by connecting to host: <xref linkend='verse_send_connect'/>.
  </para>
 </listitem>
 <listitem>
  <para>Register callbacks for data the client expects to receive: <xref linkend='verse_callback_set'/>.
  </para>
 </listitem>
 <listitem>
  <para>Send initial index subscription-command to learn about nodes on the host: <xref linkend='verse_send_node_index_subscribe'/>.
  </para>
 </listitem>
 <listitem>
  <para>Enter main loop that polls network for commands, and runs appropriate callbacks:
   <xref linkend='verse_callback_update'/>.
  </para>
 </listitem>
 <listitem>
  <para>When needed, use data representation helper functions to process data that has been received
or that is to be sent.</para>
 </listitem>
</itemizedlist>
</para>
<para>For a host application, this list would look different.</para>
</sect1>

<sect1 id='api-data-ownership'>
<title>Data Ownership</title>
<para>
As has been mentioned previously, data is passed to the application from the Verse API through <emphasis>callback functions</emphasis>.
These callbacks carry the parameters of whatever command was received, as ordinary function arguments. So, take for instance the
<xref linkend='verse_send_node_name_set'/> command. This command has two parameters: the node ID of the node whose name is to be changed,
and the new name. Because the Verse API is in C, the latter is represented as standard pointer to a character, which is simply a standard
C string (i.e., an array of characters, terminated by a character with all bits zero).
</para>
<para>
When this command is received, and unpacked, the Verse network layer will unpack the various parameters into local, temporary, variables
inside the unpacking function. It will then check its global registry of callbacks, to see if the application has registered a callback
for the command in question, and call it if there is one. In this call, it will simply pass the address of its local variable, for any
parameter represented as a pointer.
</para>
<para>
What this means for the application programmer, is that any parameter value represented as a pointer <emphasis>must</emphasis> be copied
into the application. You cannot simply store the pointer, as the memory being pointed at by the pointer will go away as the unpacking
function in the Verse library leaves its scope.
</para>
<note>
<para>Pointer arguments to callbacks point at <emphasis>temporary memory</emphasis>, owned by the Verse library (typically on the stack),
and data that the application wishes to store <emphasis>must</emphasis> be copied.
</para>
</note>
<para>
The above can be abbreviated into <quote>the Verse library doesn't store data</quote>.
</para>
</sect1>

<sect1 id='api-ref-session'>
<title>Session Management Functions</title>

<refentry id='verse_send_connect' xreflabel='verse_send_connect()'>
<refnamediv>
<refname>verse_send_connect</refname>
<refpurpose>Create a connection to a Verse host</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>
<function>
<returnvalue>
VSession
</returnvalue>
verse_send_connect</function></funcdef>
<paramdef>
 <parameter><type>const char *</type> name</parameter>,
 <parameter><type>const char *</type> pass</parameter>,
 <parameter><type>const char *</type> address</parameter>,
 <parameter><type>const uint8 *</type> expected_host_id</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function sends the connect command to a host, asking it to establish a new session. The parameters are used
to give the connecting user's identity to the host, in the form of a name and a password. How these were obtained
is currently outside the scope of this text. The third argument is simply the address, in either textual or
dotted-IP form, of the host to which the client is to connect. The fourth argument is a pointer to a buffer holding
a cached copy of that host's ID key, so that the connection can be verified to be to the same host as previously.
If no such cached key is available, specify <symbol>NULL</symbol> here.
</para>
<para>
This function returns a <type>VSession</type> value that represents the session created for the new connection,
or <symbol>NULL</symbol> on failure. The new session is also made the current one. Applications can switch between
sessions by using the <xref linkend='verse_session_set'/>() function.
</para>
</refsect1>
</refentry>


<refentry id='verse_send_connect_accept'>
<refnamediv>
<refname>verse_send_connect_accept</refname>
<refpurpose>Tell a client its connection request was accepted by a Verse host</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_send_connect_accept</function></funcdef>
<paramdef>
 <parameter><type>VNodeID</type> avatar</parameter>,
 <parameter><type>const char *</type> address</parameter>,
 <parameter><type>const uint8 *</type> host_id</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function sends the connect_accept command, which informs a connecting client that the
connection attempt was successful and that it now has established a session with the host.
</para>
<para>
This function is normally only used in hosts, a client need never call this function. A client
will, however, always need to set a callback for this command anyway, in order to learn when
its connection attempt has succeeded.
</para>
<para>
The callback for this function, which has the same signature plus the leading user pointer,
provides a way for the client to know the ID key of the host it has connected to. This key
can be stored locally, for use in subsequent <xref linkend='verse_send_connect'/>() calls.
</para>
</refsect1>
</refentry>

<refentry id='verse_send_connect_terminate'>
<refnamediv>
<refname>verse_send_connect_terminate</refname>
<refpurpose>Terminate a client's connection to a Verse host</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_send_connect_terminate</function></funcdef>
<paramdef>
 <parameter><type>const char *</type> address</parameter>,
 <parameter><type>const char *</type> message</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function sends the connect_terminate command, which is used to disconnect from a host in a controlled
manner. It is sent by a client before destroying the session, to let the host know the client is about
to disconnect.
</para>
<para>
This is a <quote>session-less</quote> command, meaning it does not need an established session to work.
This is why the first argument is the address, in domain name or dotted-IP form, to which the command
should be sent.
</para>
</refsect1>
</refentry>

<refentry id='verse_set_connect_port'>
<refnamediv>
<refname>verse_set_connect_port</refname>
<refpurpose>Set network port to use for incoming connections.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_set_connect_port</function></funcdef>
<paramdef>
 <parameter>uint16 port</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function sets the UDP/IP port used to listen for incoming Verse connections. It is only used when
writing a host-type application. Clients that want to connect to a port other than the default simply
include the port in the host name specification when connecting (using host:port syntax). Using ports
lower than 1024 is usually not possible on Unix-style operating systems, since such ports are reserved
for <quote>well-known</quote> applications.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_set'>
<refnamediv>
<refname>verse_session_set</refname>
<refpurpose>Make a session the current one, through which commands are sent</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_session_set</function></funcdef>
<paramdef>
 <parameter>VSession session</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function changes the current session. All callbacks are executed in the current session,
so to serve multiple connections a client must manually iterate through its sessions and call
<xref linkend='verse_callback_update'/>() in each.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_get'>
<refnamediv>
<refname>verse_session_get</refname>
<refpurpose>Return the current session</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>VSession <function>verse_session_get</function></funcdef>
<paramdef>
 <parameter>void</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function returns the current session, i.e. the session that is currently processed by
calls to <xref linkend='verse_callback_update'/>. It can be useful if your application is
processing multiple connections.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_get_avatar'>
<refnamediv>
<refname>verse_session_get_avatar</refname>
<refpurpose>Get host-side node ID for current session's avatar node</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>VNodeID <function>verse_session_get_avatar</function></funcdef>
<paramdef>
 <parameter>void</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function returns the host-side node identifier for the current session's avatar node. The avatar node
is an <xref linkend='n-object'/> that acts as the client's representation on the
Verse host. This ID is also delivered to the application as an argument in the
<xref linkend='verse_send_connect_accept'/>() callback.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_get_size'>
<refnamediv>
<refname>verse_session_get_size</refname>
<refpurpose>Get size of session's packet history buffer</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>size_t <function>verse_session_get_size</function></funcdef>
<paramdef>
 <parameter>void</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function returns the size of the (outbound) packet history buffer in the current session. It is a measure
of how well the network connection is working; if it is monotonically increasing over a longer period of time
(say, tens of seconds), that means data is not getting through to the other end, or that
<link linkend='packet_ack'>acknowledgments</link> of packets are not getting through in the other direction.
</para>
<para>
An application can use the value returned by this function to make a decision to drop the connection altogether,
if it exceeds some specific threshold. Such a threshold should be configurable.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_get_time'>
<refnamediv>
<refname>verse_session_get_time</refname>
<refpurpose>Get current time for active session</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_session_get_time</function></funcdef>
<paramdef>
 <parameter><type>uint32 *</type>seconds</parameter>,
 <parameter><type>uint32 *</type>fractions</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function returns the session's current time. The time is computed based on an initial value sent by
the host during the connection-establishment handshaking, and then kept up to date by the client.
</para>
<para>
The time is expressed as a fixed-point number of seconds since some arbitrary point in the past; there
is no definition of what the time shall be immediately following a connection. It is represented as two
32-bit integers; one holds the number of seconds, and the other holds a fraction for extra precision. The
fraction is expressed in 1/4,294,967,296:ths of a second, so that for instance the time <quote>16.75
seconds</quote> would be reported by setting <varname>seconds</varname>=<literal>16</literal> and
<varname>fractions</varname>=<literal>3,221,225,472</literal>.
</para>
<para>
The allocation of the above-mentioned 64 bits means that Verse can accurately represent any timestamp
from 0.0 seconds and up to about 49,710 full days, while keeping the precision of approximately
0.00000000023 seconds over the full range.
</para>
<para>
The current time is useful for determining when the translation of an object, since position and
rotation are expressed with velocity and acceleration parameters, playing object animations, and
also for deciding when to replay audio sent through an audio stream.
</para>
</refsect1>
</refentry>

<refentry id='verse_session_destroy'>
<refnamediv>
<refname>verse_session_destroy</refname>
<refpurpose>Destroy a connection to a Verse host</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_session_destroy</function></funcdef>
<paramdef>
 <parameter><type>VSession</type> session</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>This function destroys the given Verse session. Destroying a session does not send out the
<xref linkend='connect_terminate'/> command; you should do that manually.
</para>
<para>Destroying the current session will cause some other session to become current.
</para>
</refsect1>
</refentry>

<refentry id='verse_callback_set' xreflabel='verse_callback_set()'>
<refnamediv>
<refname>verse_callback_set</refname>
<refpurpose>Register a command callback, to be called when data arrives</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_callback_set</function></funcdef>
<paramdef>
 <parameter><type>void *</type> send_func</parameter>,
 <parameter><type>void *</type> callback</parameter>,
 <parameter><type>void *</type> user_data</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>This function registers a callback to be called whenever a given Verse command is received.
</para>
<para>
The command is identified by providing, in <parameter>send_func</parameter>, the address of one of the
<xref linkend='api-ref-commands'/> functions. This is done since there has to
be a complete set of such functions available in any case, and making them serve <quote>double duty</quote> as
command identifiers saves the API from having to provide e.g. an enumeration representing all commands.
</para>
<para>
The second parameter, <parameter>callback</parameter>, is the user-defined callback that is going to be called, by
<xref linkend='verse_callback_update'/>, whenever the command in question is received.
</para>
<para>
The final argument, <parameter>user_data</parameter>, is a data pointer that is simply passed to the callback, the API
itself does not use or interpret it in any way.
</para>
</refsect1>
<refsect1><title>Callback Prototypes</title>
<para>Given a command-sending function, the proper callback function has the exact same prototype, with a
single <type>void *</type> <varname>user_pointer</varname> prepended. So, take for instance the
<xref linkend='verse_send_tag_group_create'/> function. It has the following prototype:
<funcsynopsis>
 <funcprototype>
  <funcdef>void <function>verse_send_tag_group_create</function></funcdef>
  <paramdef>VNodeID <parameter>node_id</parameter></paramdef>
  <paramdef>uint16 <parameter>group_id</parameter></paramdef>
  <paramdef>const char * <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
Prepending a single <type>void *</type> <varname>user_pointer</varname> argument, we get the following prototype
for the callback:
<funcsynopsis>
 <funcprototype>
  <funcdef>void <function>cb_tag_group_create</function></funcdef>
  <paramdef>void *<parameter>user_pointer</parameter></paramdef>
  <paramdef>VNodeID <parameter>node_id</parameter></paramdef>
  <paramdef>uint16 <parameter>group_id</parameter></paramdef>
  <paramdef>const char * <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
This example also shows how the callback for a given command sending function can be named by replacing the
<function>verse_send</function> prefix with <function>cb</function>, for <quote>callback</quote>. You are, of
course, free to develop your own practice for how to name the callback functions you write.
</para>
<para>
Because of the way the API is defined, with a single entry point (this one) that accepts values of a weak type, it is
possible to pass basically anything as the <parameter>callback</parameter> value. Since the API will call it, expecting
a function with the expected prototype, things can go horribly wrong if the wrong value has been supplied. Be careful.
</para>
</refsect1>
</refentry>

<refentry id='verse_callback_update' xreflabel='verse_callback_update()'>
<refnamediv>
<refname>verse_callback_update</refname>
<refpurpose>Empty incoming network queue, and call callbacks as necessary</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>verse_callback_update</function></funcdef>
<paramdef>
 <parameter><type>uint32</type> microseconds</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function reads any incoming packets from the network, parses them (splits them into commands) and issues
calls to any callbacks that are registered for the found commands. It will block for at most <parameter>microseconds</parameter>
microseconds and wait for something to arrive.
</para>
<note><para>An application <emphasis>must</emphasis> call this function periodically in order to service the connection
with the other end of the Verse link; failure to do so will cause the other end's packet buffer to grow monotonically,
which in turn might cause the connection to be terminated.</para></note>
<para>This function really is <quote>the heart</quote> of Verse clients; any client programmer must figure out a way to get
his/her client to regularly call this function, to keep the Verse traffic flowing as required.</para>
<para>
Any callbacks registered using <xref linkend='verse_callback_set'/> can be called as a result of calling this function,
if the corresponding Verse event has happened. Execution of this function is the <emphasis>only</emphasis> time during
which callbacks can be called. This means that a client program can rely on the fact that calling some other Verse API
function, such as any command-sending function, is guaranteed to <emphasis>not</emphasis> cause a callback to be invoked.
</para>
</refsect1>
</refentry>

</sect1>

<sect1 id='api-ref-data'>
<title>Pack/Unpack Helper Functions</title>
<para>These are functions for dealing with packing and unpacking data to and from the network representation.
Normally, the Verse API hides all data pack/unpack operations, delivering already-unpacked parameters directly
to an application's callback functions. However, object method calls require extraneous information that is
not buffered by the API, so to properly unpack a call's parameters, the application needs to be in control.
</para>
<para>
Also, the separation of packing a call from actually sending it, can help improve performance if a single call
needs to be sent multiple times, since it makes it possible to buffer the packed representation and re-use it
for any number of calls.
</para>

<refentry id='verse_method_call_pack'>
<refnamediv>
<refname>verse_method_call_pack</refname>
<refpurpose>Pack a method call for network transmission</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>VNOPackedParams * <function>verse_method_call_pack</function></funcdef>
<paramdef>
 <parameter><type>uint32</type> param_count</parameter>,
 <parameter><type>const VNOParamType *</type> param_type</parameter>,
 <parameter><type>const VNOParam *</type> params</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function is used to pack a method call, prior to transmission. It accepts an array of
types, and an array of unions holding the actual values for each parameter. It creates and
returns a fairly opaque in-memory representation of the parameters, suitable for passing to
the method call sending function.
</para>
<para>
The reason this function exists is that some applications (such as host implementations) might
need to send the exact same set of parameters to several clients, and having the moderately
computationally intensive packing separate from the sending allows packing once and then re-using
the packed parameters for several sends.
<note>
<para>The current (release 2, June 2004) API implementation does not actually support doing this,
since <xref linkend='verse_send_o_method_call'/> will free the parameter block after sending it.</para>
</note>
</para>
</refsect1>
</refentry>

<refentry id='verse_method_call_unpack'>
<refnamediv>
<refname>verse_method_call_unpack</refname>
<refpurpose>Extract arguments from method call</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>verse_method_call_unpack</function></funcdef>
<paramdef>
 <parameter><type>const VNOPackedParams *</type> data</parameter>,
 <parameter><type>uint32</type> param_count</parameter>,
 <parameter><type>const VNOParamType *</type> param_type</parameter>,
 <parameter><type>VNOParam *</type> params</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
This function unpacks a memory block holding method call parameter values, as packed by
<xref linkend='verse_method_call_pack'/>() above, and fills in the supplied array of
<xref linkend='type-VNOParam'/> unions with the proper values. The <varname>param_type</varname>
array is used to determine the type of each argument, no such data is contained in the data block.
</para>
</refsect1>
</refentry>

</sect1>

<sect1 id='api-ref-commands' xreflabel='command sending'>
<title>Command Sending Functions</title>
&API;
</sect1>

</chapter>

&GNUFDL;

</book>