Skip to content

protocol.md

Latest commit

 

History

History
247 lines (180 loc) · 12.6 KB

protocol.md

File metadata and controls

247 lines (180 loc) · 12.6 KB

The PixelVloed UDP protocol for client and server

PixelVloed lets you update pixels on a screen by sending UDP packets.

About PixelVloed packets:

  • The maximum packet size is 1122 bytes.
  • There are four different protocols that encode pixels differently.
  • The number of pixels that can be sent with each packet varies for each protocol.
  • In all four protocols, the header is two bytes and the first byte determines protocol version.
  • Clients can switch between protocol versions at will between packets but not within packets.
  • All values used in messages should be little endian.

Protocols

The four protocols in summary:

  • Protocol 0: 16-bit X/Y coordinates, 24-bit RGB with optional 8-bit alpha.
  • Protocol 1: 12-bit X/Y coordinates, 24-bit RGB with optional 8-bit alpha.
  • Protocol 2: 12-bit X/Y coordinates, 8-bit RGB or 6-bit RGB and 2-bit alpha.
  • Protocol 3: 12-bit X/Y coordinates, 8-bit RGB (no alpha), uses one color for all pixels.

Protocol 0

Protocol 0 is the simplest and easiest to use. Full 24 bit colors can be used with optional alpha.

Header

Byte Bit Contents
byte 0 bit 7-0 Protocol version. (For this protocol always 0x00.)
byte 1 bit 7-1 Not used.
bit 0 Alpha enable bit. (0: alpha is disabled. 1: alpha is enabled.)

So either \x00\x00 for no alpha, or \x00\x01 for alpha.

Data

Each pixel is encoded with 7 bytes when alpha is disabled, 8 bytes when alpha is enabled.

The data part of a packet is an array of such sequences of bytes.

  • 2 bytes for the X coordinate
  • 2 bytes for the Y coordinate
  • 1 byte for R (red)
  • 1 byte for G (green)
  • 1 byte for B (blue)
  • Optionally 1 byte for A (alpha)

Pixels per message:

  • 160 when alpha is disabled
  • 140 when alpha is enabled

Pixel layout (alpha disabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 7-0 Highest 8 bits of the X coordinate of the pixel.
byte 2 bit 7-0 Lowest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 4 bit 7-0 R color value.
byte 5 bit 7-0 G color value.
byte 6 bit 7-0 B color value.

Here is an example of one packet that contains one pixel:

00000000 00000000 00000001 10000001 00000001 00001111 10000000 00000000 00000000

An explanation of this packet:

  • 00000000 00000000 signify protocol 0 with alpha disabled.
  • 00000001 10000001 signify first pixel's X = 2^8 + 2^7 + 2`1 = 385.
  • 00000001 00001111 signify first pixel's Y = 2^8 + 2^3 + 2^2 + 2^1 + 2^0 = 271.
  • 10000000 signifies first pixel's R = 127.
  • 00000000 signifies first pixel's G = 0.
  • 00000000 signifies first pixel's B = 0.

Pixel layout (alpha enabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 7-0 Highest 8 bits of the X coordinate of the pixel.
byte 2 bit 7-0 Lowest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 4 bit 7-0 R color value.
byte 5 bit 7-0 G color value.
byte 6 bit 7-0 B color value.
byte 7 bit 7-0 Alpha color value.

Here is the same example for one packet that contains one pixel:

00000000 00000000 00000001 10000001 00000001 00001111 10000000 00000000 00000000 10101010
P=0      A=off    X=385             Y=271             R=127    G=0      B=0      A=170
  • 10101010 signifies first pixel's A = 2^7 + 2^5 + 2^3 + 2^1 = 170, or 170/255 = 66,67% transparent.

Protocol 1

Only supported on the C server.

Protocol 1 is the same as protocol 0, except it only uses 12 bits per X/Y coordinate.

This uses fewer bytes when displays have 2^12 = 4096 pixels or less.

Full 24-bit colors can be used with optional alpha.

Header

Byte Bit Contents
byte 0 bit 7-0 Protocol version. (For this protocol always 0x01.)
byte 1 bit 7-1 Not used.
bit 0 Alpha enable bit. (0: alpha is disabled. 1: alpha is enabled.)

Data

Each pixel is encoded with 6 bytes when alpha is disabled, 7 bytes when alpha is enabled.

Pixels per message:

  • 186 when alpha is disabled
  • 160 when alpha is enabled

Pixel layout (alpha disabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 3-0 Highest 4 bits of the X coordinate of the pixel.
byte 1 bit 7-4 Lowest 4 bits of the Y coordinate of the pixel.
byte 2 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-0 R color value.
byte 4 bit 7-0 G color value.
byte 5 bit 7-0 B color value.

Pixel layout (alpha enabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 3-0 Highest 4 bits of the X coordinate of the pixel.
byte 1 bit 7-4 Lowest 4 bits of the Y coordinate of the pixel.
byte 2 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-0 R color value.
byte 4 bit 7-0 G color value.
byte 5 bit 7-0 B color value.
byte 6 bit 7-0 Alpha color value.

Protocol 2

Only supported on the C server.

Protocol 2 is the same as protocol 1, except it only uses a single byte to represent color.

Pixels per message:

  • 280 when alpha is disabled
  • 280 when alpha is enabled

The reason why alpha doesn't use more space is that colors are degraded.

Header

Byte Bit Contents
byte 0 bit 7-0 Protocol version. (For this protocol always 0x02.)
byte 1 bit 7-1 Not used.
bit 0 Alpha enable bit. (0: alpha is disabled. 1: alpha is enabled.)

Data

The data describes the X and Y coordinates and the R, G, B and optional alpha color values. Multiple pixels can be send in one message.

Pixel layout (alpha disabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 3-0 Highest 4 bits of the X coordinate of the pixel.
byte 1 bit 7-4 Lowest 4 bits of the Y coordinate of the pixel.
byte 2 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-5 3 bit R color value.
byte 3 bit 4-2 3 bit G color value.
byte 3 bit 1-0 2 bit B color value.

Pixel layout (alpha enabled)

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 3-0 Highest 4 bits of the X coordinate of the pixel.
byte 1 bit 7-4 Lowest 4 bits of the Y coordinate of the pixel.
byte 2 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.
byte 3 bit 7-6 2 bit R color value.
byte 3 bit 5-4 2 bit G color value.
byte 3 bit 3-2 2 bit B color value.
byte 3 bit 1-0 2 bit alpha color value.

Protocol 3

Only supported on the C server.

Protocol 3 is different from the previous protocols:

  • All pixels will be colored with the same 8-bit RGB color.
  • No optional alpha channel is available in this protocol.

Header

Byte Bit Contents
byte 0 bit 7-0 Protocol version. (For this protocol always 0x03.)
byte 1 bit 7-5 3 bit R color value for all pixels in this message.
bit 4-2 3 bit G color value for all pixels in this message.
bit 1-0 2 bit B color value for all pixels in this message.

Data

Pixels per message: 373

Byte Bit Contents
byte 0 bit 7-0 Lowest 8 bits of the X coordinate of the pixel.
byte 1 bit 3-0 Highest 4 bits of the X coordinate of the pixel.
byte 1 bit 7-4 Lowest 4 bits of the Y coordinate of the pixel.
byte 2 bit 7-0 Highest 8 bits of the Y coordinate of the pixel.

The auto-detection system

Only supported on the Python servers.

A pixelvloed server should broadcast a package advertising its settings with the following string content:

"%s:%f %s:%d %d*%d" % (PROTOCOL_PREAMBLE, PROTOCOL_VERSION, UDP_IP, UDP_PORT, width, height)

A client should listen for these packages, split it on spaces and check the preample and version fields to see if it is capable of speaking the requested protocol.

An example of a broadcasted packet would be:

pixelvloed:1.00 192.168.0.1:5005 1920*1080