The Verse Specification

A platform for sharing 3D data

Emil Brink

Eskil Steenberg

This document describes version R6 of the Verse platform. The description covers the data model, the protocol, and the client API.

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 GNU Free Documentation License.

Table of Contents

Preface

1. Introduction

1.1. What is Verse?
1.2. About this Document

2. Data Model

2.1. Perfect Data

2.2. Sessions

2.2.1. Time

2.3. Subscription

2.4. Nodes

2.4.1. Common Data

2.5. The Object Node

2.5.1. Links
2.5.2. Transform
2.5.3. Light Sources
2.5.4. Methods
2.5.5. Animation
2.5.6. Hiding

2.6. The Geometry Node

2.6.1. Layers
2.6.2. Creases
2.6.3. Bones
2.6.4. Examples

2.7. The Material Node

2.7.1. Fragments
2.7.2. Examples

2.8. The Bitmap Node

2.8.1. Bitmap Coordinates
2.8.2. Layers
2.8.3. Tiles

2.9. The Text Node

2.9.1. Language
2.9.2. Buffers

2.10. The Curve Node

2.10.1. Curves

2.11. The Audio Node

2.11.1. Audio Data Organization
2.11.2. Node Structure

2.12. Subscription Graphs

2.12.1. Common Data
2.12.2. Object Node
2.12.3. Geometry Node
2.12.4. Material Node
2.12.5. Bitmap Node
2.12.6. Text Node
2.12.7. Curve Node
2.12.8. Audio Node

3. Network Protocol

3.1. Introduction

3.2. Data Types

3.2.1. Integers
3.2.2. Reals
3.2.3. Integer Aliases
3.2.4. Strings
3.2.5. Enumerations
3.2.6. Arrays
3.2.7. Structures and Unions

3.3. Data Encoding

3.3.1. Integers
3.3.2. Reals
3.3.3. Strings
3.3.4. Enumerations
3.3.5. Arrays
3.3.6. Structures and Unions
3.3.7. Alignment
3.3.8. Examples

3.4. Node Commands

3.4.1. Structure
3.4.2. Command Symmetry

3.5. Packet Format

3.5.1. UDP/IP
3.5.2. Packets

3.6. Resend Mechanism

3.6.1. Event Compression

3.7. Security

3.7.1. Network Security
3.7.2. Access Restrictions

3.8. Command Reference

3.8.1. Command Semantics

3.9. System Node Commands

connect -- Create connection to a host.
connect_accept -- Sent by a host when it accepts a connection request.
connect_terminate -- Disconnect from a host.
ping -- General-purpose unconnected "ping" command.
packet_ack -- Positive acknowledgement; a network packet has been received.
packet_nak -- Negative acknowledgement; a network packet has been lost.
node_index_subscribe -- Request continuous updates about existing nodes.
node_create -- Create a new node.
node_destroy -- Destroy a node.
node_subscribe -- Start subscribing to a node.
node_unsubscribe -- Stop subscribing to node.
node_name_set -- Set name of a node.
tag_group_create -- Create a tag group in a node, or change an existing.
tag_group_destroy -- Destroy a tag group.
tag_group_subscribe -- Start subscribing to a tag group in a node.
tag_group_unsubscribe -- Stop subscribing to a tag group.
tag_create -- Create a new tag, or change an existing.
tag_destroy -- Destroy a tag.

3.10. Object Node Commands

o_transform_pos_real32 -- Set position, speed and acceleration of object, using 32-bit precision.
o_transform_pos_real64 -- Set position, velocity, and acceleration of an object, using 64-bit precision.
o_transform_rot_real32 -- Set the rotation, its speed and acceleration of an object, using 32-bit precision.
o_transform_rot_real64 -- Set the rotation, its velocity, and acceleration of an object, using 64-bit precision.
o_transform_scale_real32 -- Set scale of an object, using 32-bit precision.
o_transform_scale_real64 -- Set scale of an object, using 64-bit precision.
o_transform_subscribe -- Start subscribing to an object's transform matrix.
o_transform_unsubscribe -- Stop subscribing to an object's transform matrix.
o_light_set -- Set intensity of light emitted by an object.
o_link_set -- Create a new link from an object to another node, or change an existing.
o_link_destroy -- Destroy a link in an object node.
o_method_group_create -- Create a group of methods.
o_method_group_destroy -- Destroy a group of methods.
o_method_group_subscribe -- Start subscribing to a group of methods.
o_method_group_unsubscribe -- Stop subscribing to a group of methods.
o_method_create -- Create a new method.
o_method_destroy -- Destroy a method.
o_method_call -- Call a method.
o_anim_run -- Run an animation.
o_hide -- Set hidden/shown status of object.

3.11. Geometry Node Commands

g_layer_create -- Create a new geometry data layer, or change an existing.
g_layer_destroy -- Destroy a geometry data layer.
g_layer_subscribe -- Start subscribing to a layer.
g_layer_unsubscribe -- Stop subscribing to a layer.
g_vertex_set_xyz_real32 -- Set absolute position of a vertex, in 32-bit precision.
g_vertex_delete_real32 -- Delete a vertex.
g_vertex_set_xyz_real64 -- Set absolute position of a vertex, in 64-bit precision.
g_vertex_delete_real64 -- Delete a vertex.
g_vertex_set_uint32 -- Set 32-bit unsigned integer associated with a vertex.
g_vertex_set_real32 -- Set floating point value associated with a vertex, using 32-bit precision.
g_vertex_set_real64 -- Set floating point value associated with a vertex, using 64-bit precision.
g_polygon_set_corner_uint32 -- Set four 32-bit unsigned integers, associated with the corners of a polygon.
g_polygon_delete -- Delete a polygon definition.
g_polygon_set_corner_real32 -- Set four floating point numbers, associated with the corners of a polygon, using 32-bit precision.
g_polygon_set_corner_real64 -- Set four 64-bit floating point numbers, associated with the corners of a polygon.
g_polygon_set_face_uint8 -- Set an 8-bit unsigned integer, associated with a polygon.
g_polygon_set_face_uint32 -- Set a 32-bit unsigned integer, associated with a polygon.
g_polygon_set_face_real32 -- Set a floating point number, associated with a polygon, using 32-bit precision.
g_polygon_set_face_real64 -- Set a floating point number, associated with a polygon, using 64-bit precision.
g_crease_set_vertex -- Set vertex crease layer pointer.
g_crease_set_edge -- Set edge crease layer pointer.
g_bone_create -- Create a bone for skeleton animation purposes, or change an existing.
g_bone_destroy -- Destroy a bone.

3.12. Material Node Commands

m_fragment_create -- Create a new material fragment, or change an existing.
m_fragment_destroy -- Destroy a material fragment.

3.13. Bitmap Node Commands

b_dimensions_set -- Set the dimensions of a bitmap.
b_layer_create -- Create a new bitmap data layer, or change an existing.
b_layer_destroy -- Destroy a bitmap data layer.
b_layer_subscribe -- Start subscribing to a data layer.
b_layer_unsubscribe -- Stop subscribing to a data layer.
b_tile_set -- Set pixel values for a square tile of a layer.

3.14. Text Node Commands

t_language_set -- Set the langauge descriptor for a text node.
t_buffer_create -- Create a new text buffer, or rename an existing.
t_buffer_destroy -- Destroy a text buffer.
t_buffer_subscribe -- Start subscribing to a text buffer.
t_buffer_unsubscribe -- Stop subscribing to a text buffer.
t_text_set -- Set a region of text.

3.15. Curve Node Commands

c_curve_create -- Create a new curve, or change an existing.
c_curve_destroy -- Destroy a curve.
c_curve_subscribe -- Start subscribing to a curve.
c_curve_unsubscribe -- Stop subscribing to a curve.
c_key_set -- Set position of a curve key point.
c_key_destroy -- Destroy a curve key point.

3.16. Audio Node Commands

a_buffer_create -- Create a new audio buffer (a container where audio can be stored and edited), or change an existing.
a_buffer_destroy -- Destroy an audio buffer.
a_buffer_subscribe -- Subscribe to an audio buffer.
a_buffer_unsubscribe -- Stop subscribing to an audio buffer.
a_block_set -- Send and receive audio buffer data.
a_block_clear -- Clear a block of audio data.
a_stream_create -- Create a new audio stream or rename an existing.
a_stream_destroy -- Destroy an audio stream.
a_stream_subscribe -- Subscribe to an audio stream, so that any data sent through it is received.
a_stream_unsubscribe -- Stop subscribing to an audio stream.
a_stream -- Send a block of streaming audio sample data.

3.17. Command Index

4. Standard API

4.1. Introduction

4.1.1. API Goals
4.1.2. Choice of Language
4.1.3. About Callbacks

4.2. API Overview

4.3. A Typical Client

4.4. Data Ownership

4.5. Session Management Functions

verse_send_connect -- Create a connection to a Verse host
verse_send_connect_accept -- Tell a client its connection request was accepted by a Verse host
verse_send_connect_terminate -- Terminate a client's connection to a Verse host
verse_set_connect_port -- Set network port to use for incoming connections.
verse_session_set -- Make a session the current one, through which commands are sent
verse_session_get -- Return the current session
verse_session_get_avatar -- Get host-side node ID for current session's avatar node
verse_session_get_size -- Get size of session's packet history buffer
verse_session_get_time -- Get current time for active session
verse_session_destroy -- Destroy a connection to a Verse host
verse_callback_set -- Register a command callback, to be called when data arrives
verse_callback_update -- Empty incoming network queue, and call callbacks as necessary

4.6. Pack/Unpack Helper Functions

verse_method_call_pack -- Pack a method call for network transmission
verse_method_call_unpack -- Extract arguments from method call

4.7. Command Sending Functions

4.7.1. System Command Sending Functions
4.7.2. Object Command Sending Functions
4.7.3. Geometry Command Sending Functions
4.7.4. Material Command Sending Functions
4.7.5. Bitmap Command Sending Functions
4.7.6. Text Command Sending Functions
4.7.7. Curve Command Sending Functions
4.7.8. Audio Command Sending Functions

A. GNU Free Documentation License

A.1. PREAMBLE
A.2. APPLICABILITY AND DEFINITIONS
A.3. VERBATIM COPYING
A.4. COPYING IN QUANTITY
A.5. MODIFICATIONS
A.6. COMBINING DOCUMENTS
A.7. COLLECTIONS OF DOCUMENTS
A.8. AGGREGATION WITH INDEPENDENT WORKS
A.9. TRANSLATION
A.10. TERMINATION
A.11. FUTURE REVISIONS OF THIS LICENSE
A.12. ADDENDUM: How to use this License for your documents

List of Tables
2-1. Geometry Node Layer Types
2-2. Material Node Fragment Type Enumeration
2-3. Material Node Fragment Type Descriptions
2-4. Light Types
2-5. Noise Fragment Types
2-6. Blender Fragment Types
2-7. Ramp Fragment Types
2-8. Ramp Channel Types
2-9. Bitmap Node Layer Types
3-1. Integer Aliases
3-2. A System Command
3-3. A Node Command
3-4. Command Index

List of Figures
2-1. A Cube
2-2. A Plain Gray Material
2-3. Bitmap Coordinates
2-4. Keys in a Curve
2-5. Audio Buffer Blocks
2-6. Common Data Subscription Graph
2-7. Object Node Subscription Graph
2-8. Geometry Node Subscription Graph
2-9. Material Subscription Graph
2-10. Bitmap Subscription Graph
2-11. Text Subscription Graph
2-12. Curve Subscription Graph
2-13. Audio Subscription Graph

List of Examples
2-1. Cube Geometry
2-2. Plain Gray
2-3. The t_text_set Command
3-1. A signed integer
3-2. An unsigned integer
3-3. A Simple String
3-4. An International String
3-5. g_vertex_set_xyz_real32 Addressing
3-6. g_vertex_set_xyz_real32 Content

		Next
		Preface