BasaltMeter/Document/PROTOCOL.md

# Protocol

This document introduce the protocol used between Basalt Presenter and Basalt Trainer.

## Data Format

If there is no specific description, the endian of data is **native endian**.
Because all data are transmitted in local machine, so we use native endian.

During the transmission, you may faced with some weired types which is obviously don't have fixed size or not common.
I will introduce them in there about how to transmit them.

### String

When transmitting string, it will transmit an `u32` at first to indicate the length of string in **character**, NOT in **byte**.
Then we transmit the string itself without NULL terminator.
All transmitted string is UTF-8.

### BSString

Transmitting BSString is similar with String.
The only difference between String and BSString is that the char type of BSString is platform-dependent.
In Windows, it is `wchar_t` (aka. `u16`), and in POSIX, it is `char` (aka. `u8`).
So the encoding of BSString is UTF-16 on Windows and UTF-8 on POSIX.

## Command Protocol

Before introducing command protocol, it would be better to the priniciple,
that Presenter is the slave application, and Trainer is the master application.

Command protocol is tramsmitted by system named pipe.
The name of pipe is `\\.\pipe\ed0e3f1f-d214-4880-9562-640bce15e72e` on Windows 
or `/tmp/ed0e3f1f-d214-4880-9562-640bce15e72e` on POSIX.

|Code|Mnemonic|Direction|Comment|
|:---|:---|:---|:---|
|`0x61`|HANDSHAKE_REQUEST|Presenter<--Trainer|Handshake code (Are Presenter ready?)|
|`0x62`|HANDSHAKE_RESPONSE|Presenter-->Trainer|Handshake code (Presenter is ready).|
|`0x01`|DATA_READY|Presenter-->Trainer|Data was ready by Presenter. Trainer please receive it.|
|`0x02`|DATA_RECEIVED|Presenter<--Trainer|Data has been received by Trainer. Please go into next loop.|
|`0x21`|ACTIVELY_STOP|Presenter-->Trainer|Something was happened in Presenter and it want to stop.|
|`0x71`|STOP_REQUEST|Presenter<--Trainer|Trainer order Presenter to stop and quit.|
|`0x72`|STOP_RESPONSE|Presenter-->Trainer|Presenster is stopped.|

### Handshake

At the beginning of execution, 
Trainer send handshake code to Presenter first and then Presenter send another handshake code to Trainer back. 
After this, both 2 applications start running.

When Trainer send handshake code, 
Trainer should attach some values following it to indicate some essential properties of data
which instruct Representer how to generate data.
There is a table introduce these properties:

|Data Type|Mnemonic|Comment|
|:---|:---|:---|
|u8|HEADLESS|True for headless mode. `0` for false and any other value for true.|
|u8|PIXEL_KIND|The pixel kind of image|
|u32|WIDTH|The width of image|
|u32|HEIGHT|The height of image|
|BSString|ENGINE_NAME|The name of used engine.|
|u32|ENGINE_DEVICE|The index of device used by engine.|
|BSString|DELIVER_NAME|The name of used deliver.|
|u32|DELIVER_DEVICE|The index of device used by deliver.|
|BSString|OBJECT_LOADER_NAME|The name of used object loader.|
|BSString|OBJECT_LOADER_FILE|The path to file loaded by object loader.|
|BSString|ANIME_LOADER_NAME|The name of used anime loader.|
|BSString|ANIME_LOADER_FILE|The path to file loaded by anime loader.|

For the all possible values of "PIXEL_KIND" in above table, there is also a table:

|Value|Comment|
|:---|:---|
|`0x01`|Grayscale represented by one float32|
|`0x02`|Grayscale represented by one u8|
|`0x03`|RGB represented by three float32|
|`0x04`|RGB represented by three u8|

## Data Protocol

### Pipe

For this kind deliver, it is tramsmitted by system named pipe.
The name of pipe is `\\.\pipe\ebe2a39d-75de-4cf4-933f-c50284149d63` on Windows 
or `/tmp/ebe2a39d-75de-4cf4-933f-c50284149d63` on POSIX.