-
Notifications
You must be signed in to change notification settings - Fork 20
Specification of Layer Commands
Layers are used for array or hash table like data structures. All items in one layer have to have same type. It is allowed to have in layers all verse data types except string8. When client subscribes to layer, then Verse server starts to send to client all items from the layer and all further changes from this layer.
Two layers can have parent-child relation between each other. It is useful, when you share 3D geometry with other properties (e.g.: color of vertices). Imagine that we have parent layer with position of vertices and child layer with colors:
0 1 2 3 4 5 6
+---+---+---+ +---+---+---+
| | | | | | | | x
Parent +---+---+---+ +---+---+---+
layer vertex pos: | | | | | | | | y
| +---+---+---+ +---+---+---+
| | | | | | | | | z
| +---+---+---+ +---+---+---+
| +---+ +---+ +---+---+
V | | | | | | | r
Child +---+ +---+ +---+---+
layer vertex col: | | | | | | | g
+---+ +---+ +---+---+
| | | | | | | b
+---+ +---+ +---+---+
Previous ascii art image shows that layer can include holes, because some vertex was for instance deleted or it was not created yet. Child layer need not to have same number of items as parent layer. Unset items have some default valued specified in application. When item is destroyed in parent layer, then all items with same item ID are considered as destroyed in all child layers.
This command is sent by Verse server to client, when client subscribed to node containing layer. This command can be also sent from client to Verse server, when client wants to create new empty layer. The command has following structure:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | PL ID | LayID | D | C | CT |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
More detail description of structure:
0 1 1 2 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------+
| OpCode=128 |
+---------------+
| Length=15 |
+---------------+
| Share=0/4/6 |
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Parent Layer ID |*
+---------------+---------------+
| Layer ID |
+---------------+---------------+
| Data Type |
+---------------+
| Count |
+---------------+---------------+
| Custom Type |
+---------------+---------------+
Items of command have following purpose:
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where server/client wants to create new layer.
- Parent Layer ID: the ID of parent layer.
- Layer ID: the ID of new layer (it is unique inside node). When client sends this command, then this value has to be -1 (0xFFFF).
- Data Type: data type of all items in new layer as it is described in Data Types. Note: string8 can't be item of layer.
- Count: count of values stored in one item of layer. It could be: 1, 2, 3, 4.
- Custom Type: user defined type of this layer.
This command can be sent by client, when client wants to destroy some layer and it has write asses to the node containing this layer. This command is also sent by server, when some layer is destroyed. When parent layer is destroyed, then Verse server will destroy all child layers too and clients will receive corresponding commands about this destroying. The command has following structure:
0 1 2 3 4 5 6 7 8
+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | TayID |
+---+---+---+---+---+---+---+---+---+
More detail description of structure:
+---------------+
| OpCode=129 |
+---------------+
| Length=9 |
+---------------+
| Share=0/4 |
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |
+---------------+---------------+
Items of command have following purpose:
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where server/client wants to destroy layer.
- Layer ID: the ID of destroyed layer.
When client wants to subscribe to layer, then it has to send following command to the Verse server. When client has at least read access right to node containing layer, then Verse server will send to the client set of Layer Set commands that are described later on this page. The command has following structure:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Version | CRC32 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
More detail description of structure:
+---------------+
| OpCode=130 |
+---------------+
| Length=17 |
+---------------+
| Share=0/4 |
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |
+---------------+---------------+---------------+---------------+
| Version |
+---------------+---------------+---------------+---------------+
| CRC32 |
+---------------+---------------+---------------+---------------+
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where client wants to subscribe to the layer
- Layer ID: the ID of subscribed layer.
- Version: Version of layer (not supported yet and should be 0).
- CRC32: CRC32 of layer (not supported yet and should be 0).
When client does not want to receive changes of layer anymore, then it has to send layer unsubscribe command:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Version | CRC32 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
More detail description of structure:
+---------------+
| OpCode=131 |
+---------------+
| Length=17 |
+---------------+
| Share=0/4 |
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |
+---------------+---------------+---------------+---------------+
| Version |
+---------------+---------------+---------------+---------------+
| CRC32 |
+---------------+---------------+---------------+---------------+
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where client wants to unsibscribe from layer
- Layer ID: the ID of unsubscribing layer.
- Version: Version of layer (not supported yet and should be 0).
- CRC32: CRC32 of layer (not supported yet and should be 0).
When client send following command, then one item of layer will be destroyed and it will have default or unset value. Implementation details are at developers. When item is destroyed, then rest of layer is unchanged, but when layer has at least one child layer, then all items with same item ID are considered as destroyed in all child layers. This command can send Verse server too, when item is destroyed at server. Command has following structure:
0 1 2 3 4 5 6 7 8 9 10 11 12
+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
More detail description of structure:
+---------------+
| OpCode=132 |
+---------------+
| Length=13 |
+---------------+
| Share=0/4/6 |
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |
+---------------+---------------+---------------+---------------+
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where server/client wants to destroy item.
- Layer ID: the ID of layer, where server/client wants to destroy item.
- Item ID: the ID of item that server/client wants to destroy.
There are several layer set value commands. Every command differs in data type and count of values stored in one item of layer. The same command for creating new item of layer is also used for changing value of item.
Commands for setting values are similar for setting values of tags. There are also four variants o command for one data type. Every variant differs in number of values in each item:
0 1 2 3 4 5 6 7 8 9 10 11 12 13
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID | V | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
There is one big difference in sharing of address, when this command uses compression. Consider situation, when you send many Layer Set Value commands with same OpCode (btw: this situation can happen very often), then it is very inefficient to send it in following way:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID=5 | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID=6 | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
Following variant is not much more better, because Item ID is incremented from previous Item ID.
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID=5 | V | V | V | Item ID=6 | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
Thus Layer Set Value enable to share Item ID between command, when you send sequence of items, where Item ID of each command is one greater than Item ID of previous command. Item of structure Item ID contains then Item ID of first command in sequence. It is possible to compute how many sub-commands are compressed in one command from item: Length. Example of such compression is described at following ascii art image:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| O | L | S | Node ID | LayID | Item ID=5 | V | V | V | V | V | V |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
\ /
+-----------------------+------------------------+
|
shared address
More detail description of command structure:
+---------------+
| OpCode=133 | (134,135,136)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (uint8) | (133,134,135,136)
+---------------+
| Value (uint8) | (134,135,136)
+---------------+
| Value (uint8) | (135,136)
+---------------+
| Value (uint8) | (136)
+---------------+
- OpCode: identifier of this command.
- Length: minimal length of this command.
- Share: the length of address in bytes that is shared between commands with same OpCode.
- Node ID: the ID of node, where client/server wants to set value of layer item.
- Layer ID: the ID of layer, where client/server wants to set value of layer item.
- Layer ID: the ID of the item, where will be create/changed value.
- Value: value(s) of tag. Command with OpCode equal to 133 has only one value. Command with OpCode equal to 134 has two values, etc.
Note: Commands for setting other data types are analogous. Thus there is only detail description of commands structures for following commands.
+---------------+
| OpCode=137 | (138,139,140)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (uint16) | (137,138,139,140)
+---------------+---------------+
| Value (uint16) | (138,139,140)
+---------------+---------------+
| Value (uint16) | (139,140)
+---------------+---------------+
| Value (uint16) | (140)
+---------------+---------------+
+---------------+
| OpCode=141 | (142,143,144)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (uint32) | (141,142,143,144)
+---------------+---------------+---------------+---------------+
| Value (uint32) | (142,143,144)
+---------------+---------------+---------------+---------------+
| Value (uint32) | (143,144)
+---------------+---------------+---------------+---------------+
| Value (uint32) | (144)
+---------------+---------------+---------------+---------------+
+---------------+
| OpCode=145 | (146,147,148)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (uint64) | (145,146,147,148)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (uint64) | (146,147,148)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (uint64) | (147,148)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (uint64) | (148)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
+---------------+
| OpCode=149 | (150,151,152)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (real16) | (149,150,151,152)
+---------------+---------------+
| Value (real16) | (150,151,152)
+---------------+---------------+
| Value (real16) | (151,152)
+---------------+---------------+
| Value (real16) | (152)
+---------------+---------------+
+---------------+
| OpCode=153 | (154,155,156)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (real32) | (153,154,155,156)
+---------------+---------------+---------------+---------------+
| Value (real32) | (154,155,156)
+---------------+---------------+---------------+---------------+
| Value (real32) | (155,156)
+---------------+---------------+---------------+---------------+
| Value (real32) | (156)
+---------------+---------------+---------------+---------------+
+---------------+
| OpCode=157 | (158,159,160)
+---------------+
| Length |
+---------------+
| Share=0/4/6/10|
+---------------+---------------+---------------+---------------+
| Node ID |*
+---------------+---------------+---------------+---------------+
| Layer ID |*
+---------------+---------------+---------------+---------------+
| Item ID |*
+---------------+---------------+---------------+---------------+
| Value (real64) | (157,158,159,160)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (real64) | (158,159,160)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (real64) | (159,160)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
| Value (real64) | (160)
+---------------+---------------+---------------+---------------+
| |
+---------------+---------------+---------------+---------------+
- Home
- C/C++ API
- Basic Functions
- Node Functions
- Tag Functions
- Layer Functions
- Python API
- Session Methods
- Node Methods
- Tag Group Methods
- Tag Methods
- Layer Mehods
- Specification
- Data Types
- Transport Layer
- Security
- Structure of Packet and Message
- User Authentication
- Negotiation
- Handshake of Datagrame Connection
- Teardown of Datagrame Connection
- Resend Mechanism
- Congestion Control
- Flow Control
- TCP Variant
- Websocket Variant
- Node Commands
- Tag Group Commands
- Tag Commands
- Layer Commands