2.12. Subscription Graphs

2.12.1. Common Data

The following figure represents the top-level common node data, that is available in all nodes:

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:

1. The initial status, symbolized by the upper-most node labeled "None" is that the client knows nothing about the available nodes. By sending a 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.

2. Assuming nodes of the specified type(s) exist, the client will end up in a state where it receives the node_create (and node_destroy) commands, providing it with information about the existing nodes.

3. By sending a 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 tag_group_subscribe command to request a subscription to it.

4. 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.

Each client has a "position" 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.

2.12.2. Object Node

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.

1. Objects have light and 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 transform, 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.

2. Sending the o_transform_subscribe command switches to the bottom left state, and causes the host to start sending updates to the object's transform.

3. Sending the 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.

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 "states" are not mutually exclusive.

2.12.3. Geometry Node

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.

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 g_layer_subscribe. Doing so forces the client to chose a desired precision for any floating-point numbers in the layers.

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 g_vertex_set_xyz_real32 or 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 g_vertex_set_real32 or g_vertex_set_real64 depending on the precision at which the client is operating.

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.

2.12.4. Material Node

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.

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.

2.12.5. Bitmap Node

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.

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.

Having subscribed to a layer, its contents will be delivered (and kept up to date) by the host through the use of the b_tile_set command.

2.12.6. Text Node

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.

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 t_buffer_subscribe command.

Once subscribed to a buffer, a client will learn about its contents through receiving the t_text_set command, as shown in the lower part of the figure.

2.12.7. Curve Node

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.

The curve node's data is arranged into curves, 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 c_curve_subscribe command.

Once subscribed to a curve, a client receives a copy of its contents (which continue to arrive if the contents change) through the c_key_set and c_key_destroy commands.

2.12.8. Audio Node

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.

Audio data is arranged into buffers and streams, each of which can be subscribed to using either the a_buffer_subscribe or the a_stream_subscribe command, respectively. If subscribed to a buffer, a client will receive any data sent out to it, through the a_block_set command. Data sent to a stream will arrive through the a_stream command.

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 "states" are not mutually exclusive, here.