Common Verse Pitfalls

Sketch 0.3

This document describes a few things to keep in mind when you're new to verse programming, and especially if you're going to use the low-level API.

Note that almost all of the information in this document may be found in the most excellent specification. However, I've been told not everyone enjoys reading it.

The Design and its Consequences

General Issues

  1. The verse API does not store data. No, it does not store data. You need to do that yourself, or use a library that does it for you. There are several available, including Enough and Ample
  2. You can never know if you have received all the data on the server. This is by design, as everything is intended to be dynamic. You must always be prepared for anything to change, at any time.

  3. You usually know when an operation succeeded, since you get the command back. That is, unless your operation was undone by someone else before it got back to you. However, you cannot ever truly know if an operation failed, since there are no user-level error notifications.

    Therefore, it's better to think of outgoing commands as requests, not commands. The current state is defined by what you actually get sent back to you, not by what you requested.

  4. You only get sent the data you've explicitly subscribed to. This includes both node types, nodes and node elements. For a detailed overview, see the subscription graphs.

  5. You cannot specify a name when you create a node. You have to create the node, get it sent back to you and then set the name. Also note that the server will assign a default name upon creation, which you will probably get before you've had time to set your own.

    The workaround used in Ample is to make a FIFO of requested names. Then use these names for those nodes of the ones you get back that are owned by you.

  6. The node_list command should really be named node_type_subscribe, since that's what it really does. Unless you issue a node_list command, no nodes will be sent to you.
  7. You must wait until your connection is accepted before you issue a node_list command.
  8. You must call the callback_update function continuously, or your connection will be terminated. No exceptions are made for programs that cannot do this.
  9. Yes, there really are two kinds of links between nodes; object node links and link tags. The former have certain specified uses in the standard, while the latter do not.

  10. When you need to supply an invalid value to a function or command, use these:

    Type Value
    real32 REAL32_MAX
    real64 REAL64_MAX
    uint8
    uint32
    VNodeID ~0
    VLayerID ~0
    VBufferID ~0
  11. Verse commands, in general, are not ordered. There are certain places where order is guaranteed, such as the behaviour specified by the subscription graphs, and t_text_set commands. In general, however, you cannot assume that you will get commands back in the order in which you sent them.

Geometry

  1. Due to something called command symmetry, there are two commands for deleting vertices, and you need to keep track of which one to use all by yourself.

  2. A polygon is created when you get the corresponding g_polygon_set_corner_uint32 command. However, it's not valid until at least the first three of the vertices it references are made valid.

    For more information, see the geometry node.

  3. It is generally recommended that you reuse polygon and vertex ID:s when modifying a geometry node. The server may decide to deny your requests if you make large enough gaps in polygon and vertex stacks.
  4. A vertex position can never be explicitly set to all REALnn_MAX, since that transforms it into the corresponding a delete command. Therefore, you may safely use this state to indicate a deleted vertex in your local copy of a node's geometry data.

Text

  1. The text node command t_text_set does not send you the current state of a given text buffer. Instead, it sends you an operation to be performed on the current state. You need to implement your own text operations.
  2. The language setting is per node, not per buffer.

Interaction With Other Languages

  1. As of R5, you will get a compile-time warning for every call to callback_set from C++, no matter what you do. Sorry about that.
  2. The Verse API is very fond of layering unions of C structs on top of binary chunks of data. This may make higher-level language support a bit tricky at times.

© elmindreda