Auxiliary Spec

This is a document that outlines recommendations for how to use the Verse protocol beyond the basic specification. All the guidelines in this spec are purely optional, but they are designed to make applications work better together. The Verse spec is very flexible, but at times this flexibility is not very useful and instead it is better to have a tighter definition. Providing such a tightening is the goal of this document. Many times, as a Verse programmer, you get to choose names for layers and other things, and instead of having everyone choose their own names this document serves as a good guide. However it should never be assumed that other applications follow these recommendations.

Currently, this document is simply split into a number of sections, each of which details some area where we feel some "guidance" is important. These are the sections:

	Link Labels
	Layer Names
	Selection
	Security
	Physics
	Cameras
	Misc. Tags

Link Labels

When connecting nodes together by creating links in an object node, the application gets to specify a textual label which identifies the purpose of the link. These are the recommended labels to use for various common use-cases:

	Geometry: use "geometry" to denote that the link target is a geometry node that describes the look of the source object. This is in the core spec and just repeated here for clarity.
	Audio: use "audio" to denote that the link target is an audio node that is to be positioned at the location of the source object node.

Layer Names

Any geometry layer can be referenced by the material node using the Geometry fragment, and any texture layer can be referenced using the Texture fragment. Depending on the use of the layers it is useful to name them in a way that describes their content. All these layers can be either monochromatic, or have the suffixes "_r", "_g" and "_b" for red green and blue to indicate color.

If a layer contains monochrome color information, the recommended layer name to use is:

color

So, applying the rule about suffixes above, this means that the layer names for red, green and blue color data then become:

	color_r
	color_g
	color_b

For a layer containing transparency, the recommended layer names are:

	transparency
	transparency_r
	transparency_g
	transparency_b

Please note that there is no "color_a" or "alpha", alpha channels should be encoded as "transparency". The reason for this is that alpha is usually monochrome, whereas transparency can be both monochrome or have color.

For layers containing reflection information, the recommended layer names are:

	reflection
	reflection_r
	reflection_g
	reflection_b

For layers storing pre-computed lighting information, such as light maps or per-vertex
lighting, the recommended names are:

	light
	light_r
	light_g
	light_b

For mattes, masks that are used to hide parts of an image during compositing, the recommended names are:

	mask
	mask_r
	mask_g
	mask_b

For texture mapping, the recommended naming of the geometry layers are:

	map_u
	map_v
	map_w

Geometry creasing information, as used to control the subdivision surface meshes Verse uses, can be stored in per-vertex and per-edge (actually per-polygon) layers, named like so:

	crease
	crease_vertex
	crease_edge

Selection

For many editing applications, having Verse-distributed selection is very useful. All selections should be floating point values in order to support "soft selections", where something can be partially selected. If an application or operation only supports boolean selection, any value greater than zero should be considered selected.

For nodes this can be done with a real-typed tag named "selection".

For geometry and bitmaps this can be in the form of a layer named "selection".

If a vertex-real geometry layer is used as a select layer, other types of selectons can be derived. A polygon selection can be derived if all vertices used by the polygon are selected, and edge selection can be derived if both vertices that make up the edge are selected.

For audio layers and curves, two real-type tags named "selection_start" and "selection_end" are used to define a range of the selection.

Security

For the tagging of avatar object nodes, the recommendation is to use a tag group called "avatar" containing the following text tags:

"name" is the user name of the connection
"user_group" is used to indicate the user group the user is a member of.

Note that a connection can be a member of more than one group. Two user groups that should be used are "superuser" for a connection that has the power to modify any data, including other users' rights, and "guest" for connections without a registered user or the lowest possible level of rights. A tag named "password" may be used to store the connection's password (note that this obviously has to be hidden for most users).

A node may also have a tag group named "user" that can contain "user_group" and/or "name" tags that control what users are allowed to modify the node.

Physics

Were physics are used with Verse data, SI units are preferred, such as the metric system. Physical properties can be stored in multiple places such as geometry layers, material output labels, and tags. Whenever you store these values used for physical simulations in tags the tag group should be named "physics".

Physical data should be named after what is stores, not in what unit it is stored. Examples:

temperature (Kelvin)
weight (kilograms)
COM (Center of mass)

Any time a non-SI unit is used (should be avoided if possible) then the naming should be using the convention, <what is stored>_<single unit>. For example:

weight_pound

Games

Standard tag group for objects in game-like applications is "game", with tags:

	health
	experience
	money
	class

Cameras

To identify cameras, we use object nodes with the tag group "camera". The camera is oriented at the object's position, and always looks along the negative Z axis. Tags in this group include:

	aspect
	field_of_view
	focus_distance
	shutter_speed
	clip_near
	clip_far
	resolution_x - integer
	resolution_y - integer
	framerate
	orthogonal - boolean

Misc. Tags

Nodes may have meta data stored in text tags using the names "author" for the user name of the author of the node, "editor" for the tool that created or edited the data, "revision" for version number of the data. Include version number.

Application-specific tags should be named with the application name as a prefix, like "blender:something". Such groups should include a version string tag to specify what version of the application it applies to.

We should look into the RDF standard as used in the creative commons.