Drag[en]gine Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{tag>motioncapture democap network}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DEMoCap: Drag[en]gine Motion Capture]] >> [[democap:uipanelcapture|UI: Panel Session]] >> **DEMoCap Network Specification**
</WRAP>

====== DEMoCap Network Specification ======

The DEMoCap Networking uses the [[gamedev:dnp|Drag[en]gine Network Protocol]] as protocol and defines a set of <wrap hi>messages</wrap> and <wrap hi>linked states</wrap> supported by DEMoCap. The specification can change with upcoming DEMoCap updates but stays backwards compatible. Servers and clients are required to ignore unknown messages and linked states.

To implement this protocol best use [[https://github.com/LordOfDragons/denetwork/releases|Drag[en]gine Network Library]] and add the necessary message and state handling.
===== Frame Number =====

Various messages use //FrameNumber// to indicate in what update frame a message has been generated. To avoid delayed old messages interfering with new messages the following pseudo-code has to be used:

<code>
int32 Difference = (int32)FrameNumber - (int32)LastReceivedFrameNumber
if Difference == 0 then ignore message // duplicate
if Difference < -32767 then Difference += 65536 // wrap around uint16
if abs(Difference) > WindowSize then ignore message
if Difference < 0 then ignore message
process message
</code>

WindowSize is by default 180 unless message define a different value.

====== Messages ======

These are all messages the server and the client can send to each other.

===== Connect Request =====

Upon connecting the client has to send this message to request access to DEMoCap indicating the kinds of features it supports. The connect request message has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''1'' |
| [[gamedev:dnp#data_types|Byte]][16] | Signature | Identifies the connecting client as a DEMoCap client. Value has to be ''![DEMoCap-Client-0]!''. |
| [[gamedev:dnp#data_types|UInt]] | SupportedFeatures | <WRAP>
Features supported by the client. Flags value with these possible values:
  * Bit ''0'': Enable //Vertex Position Set// data to be send by client and server. If enabled certain messages contain additional data elements.
</WRAP> |
| [[gamedev:dnp#data_types|String8]] | Name | Name describing the remote client connecting. This is a free form name of short length indicating what software is connecting. It is used only to show the user who is connected to identify the individual connections. |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

The server will then respond with a [[#connect_accepted|Connect Accepted]] message or disconnect the client if rejected.

===== Connect Accepted =====

Send by the server after a client connects which send [[#connect_request|Connect Request]] message identifying itself as a DEMoCap client. This is the first message received from the server. The client should not send any messages until it has received this message as this will get him disconnected. The message is send reliable and has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''2'' |
| [[gamedev:dnp#data_types|Byte]][16] | Signature | Identifies the server as a DEMoCap server. Value is <wrap hi>''![DEMoCap-Server-0]!''</wrap>. If this value is not matching the client has to disconnect immediately as it is not connecting to a DEMoCap server. |
| [[gamedev:dnp#data_types|UInt]] | EnabledFeatures | Enabled features supported by both the connecting client and the server. Same possible values as in //SupportedFeatures// in [[#connect_request|Connect Request]] message |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

===== Actor Capture Bone Layout =====

Send by the server if the bone layout used for motion capture changes. Bone layouts do change if a different character configuration has been activated or the character configuration changed. Layout contains the entire bone hierarchy for the active character. Each bone is marked static or dynamic. Dynamic bones are affected by motion transfer rules. Static bones are not affected by motion transfer rules. Send are all bones since static bones can still be animated due to playing back a previous animation or using a base animation. The dynamic flag can be used by clients to know which data is motion capture and which data has other source. The message is send reliable and has this format:

^  Type                                          ^  Name                   ^  Description                                                                                                                           ^
| [[gamedev:dnp#data_types|Byte]]                | Code                    | Message code. Is value ''3''                                                                                                           |
| [[gamedev:dnp#data_types|Byte]]                | Revision                | Revision number incremented by one (with wrapping at 0xff) each time a new bone layout is send.                                        |
| [[gamedev:dnp#data_types|UShort]]              | BoneCount               | Count of bones. Can not be larger than 0x7fff.                                                                                         |
| BoneData[BoneCount]                            | Bones                   | //BoneCount// bone data.                                                                                                               |
| [[gamedev:dnp#data_types|UShort]]              | VertexPositionSetCount  | Only present if feature bit ''0'' has been enabled while connecting. \\ Count of vertex position sets. Can not be larger than 0x7fff.  |
| VertexPositionSetData[VertexPositionSetCount]  | VertexPositionSets      | Only present if feature bit ''0'' has been enabled while connecting. \\ //VertexPositionSetCount// vertex position set data.           |
|  -                                             | Reserved                | Reserved for future expansion. Ignore any additional bytes in the message                                                              |

//BoneData// has this format:
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|String8]] | Name | Name of bone. |
| [[gamedev:dnp#data_types|Short]] | Parent | Index of parent bone or -1 if root bone. |
| [[gamedev:dnp#data_types|Vector]] | Position | Position relative to rig or parent bone. |
| [[gamedev:dnp#data_types|Quaternion]] | Orientation | Origin orientation in rig or parent bone. |

//VertexPositionData// has this format (all weights are 0):
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|String8]] | Name | Name of vertex positionset. |

===== Actor Capture Frame =====

Send by the server for each motion capture frame. Motion capture data is in bone local space. The root bones are relative to either the actor position relative to the scene or the selected capture object. Capture frames match a specific bone layout revision. The client has to use the latest received bone layout. Capture frames belonging to different bone layouts have to be discarded. This avoids clients trying to read capture frames using the wrong layout. The message is send unreliable and has this format:

^  Type                                           ^  Name                          ^  Description                                                                                                                                                                                                                                                                             ^
| [[gamedev:dnp#data_types|Byte]]                 | Code                           | Message code. Is value ''4''                                                                                                                                                                                                                                                             |
| [[gamedev:dnp#data_types|UShort]]               | [[#frame_number|FrameNumber]]  | Frame number of capture frame. Used to avoid delayed old frames interfering with new frames.                                                                                                                                                                                             |
| [[gamedev:dnp#data_types|Byte]]                 | BoneLayoutRevision             | Bone layout revision matching this capture frame.                                                                                                                                                                                                                                        |
| [[gamedev:dnp#data_types|Vector]]               | Position                       | Position of actor. This is either the actor position relative to the scene or the selected capture object.                                                                                                                                                                               |
| [[gamedev:dnp#data_types|Quaternion]]           | Orientation                    | Orientation of actor. This is either the actor position relative to the scene or the selected capture object.                                                                                                                                                                            |
| [[gamedev:dnp#data_types|Float]]                | Scale                          | Scale of actor.                                                                                                                                                                                                                                                                          |
| BoneState[BoneCount]                            | Bones                          | //BoneCount// bone states as described below. //BoneCount// matches //BoneCount// from the bone layout with //Revision// matching //BoneLayoutRevision//.                                                                                                                                |
| VertexPositionSetState[VertexPositionSetCount]  | VertexPositionSets             | Only present if feature bit ''0'' has been enabled while connecting. \\ //VertexPositionSetCount// vertex position set states as described below. //VertexPositionSetCount// matches //VertexPositionSetCount// from the bone layout with //Revision// matching //BoneLayoutRevision//.  |
|  -                                              | Reserved                       | Reserved for future expansion. Ignore any additional bytes in the message                                                                                                                                                                                                                |

//BoneState// has this format:
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Vector]] | Position | Position of the bone in bone local space. |
| [[gamedev:dnp#data_types|Quaternion]] | Orientation | Orientation of the bone in bone local space. |

//VertexPositionSetState// has this format:
^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|float]] | Weight | Weight of vertex position set. |

====== Linked States ======

These are all linked states the client can request.

===== Record/Playback =====

Send by the server to link the record/playback state. The link message has this format:

^  Type  ^  Name  ^  Description  ^
| [[gamedev:dnp#data_types|Byte]] | Code | Message code. Is value ''1'' |
|  -  | Reserved | Reserved for future expansion. Ignore any additional bytes in the message |

The client has to add these values to the state in this specified order:
^  Index  ^  Type  ^  Name  ^  Description  ^
|  ''0''  | [[gamedev:dnp#state_value_data_types|UInt8]] | Status | <WRAP>
Status of the recording. Can be one of these values:
  * ''0'': Neither recording nor playing back.
  * ''1'': Preparing to record. The user is shown in the HMD a progress bar indicating the time until recording begins.
  * ''2'': Recording.
  * ''3'': Playing back.
  * ''4'': Playback paused.
</WRAP> |
|  ''1''  | [[gamedev:dnp#state_value_data_types|UInt8]] | FrameRate | Frame rate used for recording. |
|  ''2''  | [[gamedev:dnp#state_value_data_types|Float32]] | PrepareTime | Prepare waiting time in seconds. |
|  ''3''  | [[gamedev:dnp#state_value_data_types|Float32]] | PlaySpeed | Playback speed multiplier. |
|  ''4''  | [[gamedev:dnp#state_value_data_types|Float32]] | PlayTime | Playback time in seconds. |
|  ''5''  | [[gamedev:dnp#state_value_data_types|Float32]] | PlayPosition | Playback position in seconds. |

===== Revision =====

^ Date      | Changes                                   |
| 9.5.2023  | <WRAP>
  * Added support for Vertex Position Sets (Feature Bit ''0'')
</WRAP> |
Drag[en]gine Wiki

User Tools

Site Tools

Page Tools
