Documentation
¶
Overview ¶
Package protocol defines the wire format for gogpu/compose inter-process communication. It is the leaf package in the internal dependency graph — imported by transport implementations but importing nothing internal itself.
The protocol is built around a fixed 64-byte binary frame header that precedes every message on the wire. Headers use little-endian byte order and are designed to be cache-line aligned on modern hardware.
All encode/decode functions operate on caller-provided byte buffers to achieve zero allocations on the hot path. This is critical for sustained 60 FPS frame delivery.
Wire format version: 1 Magic bytes: 0x43 0x4F 0x4D 0x50 ("COMP")
Index ¶
- Constants
- Variables
- func Encode(h *Header, buf []byte) error
- func EncodeHello(msg *HelloMsg, buf []byte) error
- func EncodeWelcome(msg *WelcomeMsg, buf []byte) error
- func GetName(msg *HelloMsg) string
- func SetName(msg *HelloMsg, name string)
- type Compression
- type Flag
- type Header
- type HelloMsg
- type MsgType
- type PixelFormat
- type TransportType
- type WelcomeMsg
Constants ¶
const HandshakeSize = 128
HandshakeSize is the fixed size in bytes of both HelloMsg and WelcomeMsg.
const HeaderSize = 64
HeaderSize is the fixed size in bytes of the wire frame header. It is designed to be cache-line aligned (64 bytes on modern CPUs).
const ProtocolVersion uint16 = 1
ProtocolVersion is the current wire protocol version.
Variables ¶
var ( // ErrHandshakeBufTooSmall is returned when the buffer is smaller than HandshakeSize. ErrHandshakeBufTooSmall = errors.New("protocol: handshake buffer too small (need 128 bytes)") // ErrHandshakeInvalidMagic is returned when handshake magic bytes are wrong. ErrHandshakeInvalidMagic = errors.New("protocol: handshake invalid magic (expected 0x434F4D50)") // ErrRejected is returned when the compositor rejected the connection. ErrRejected = errors.New("protocol: connection rejected by compositor") )
Handshake errors.
var ( // ErrBufferTooSmall is returned when the provided buffer is smaller than HeaderSize. ErrBufferTooSmall = errors.New("protocol: buffer too small (need 64 bytes)") // ErrInvalidMagic is returned when the decoded magic bytes do not match "COMP". ErrInvalidMagic = errors.New("protocol: invalid magic (expected 0x434F4D50)") // ErrUnknownMsgType is returned when the decoded message type is not recognized. ErrUnknownMsgType = errors.New("protocol: unknown message type") )
Errors returned by Encode and Decode.
var Magic = [4]byte{0x43, 0x4F, 0x4D, 0x50}
Magic is the 4-byte protocol identifier at the start of every header. ASCII: "COMP" (0x43, 0x4F, 0x4D, 0x50).
Functions ¶
func Encode ¶
Encode writes the header h into buf using little-endian byte order. buf must be at least HeaderSize (64) bytes. Encode never allocates.
func EncodeHello ¶
EncodeHello writes a HelloMsg into buf using little-endian byte order. buf must be at least HandshakeSize (128) bytes. Never allocates.
func EncodeWelcome ¶
func EncodeWelcome(msg *WelcomeMsg, buf []byte) error
EncodeWelcome writes a WelcomeMsg into buf using little-endian byte order. buf must be at least HandshakeSize (128) bytes. Never allocates.
Types ¶
type Compression ¶
type Compression uint8
Compression identifies the payload compression algorithm.
const ( // CompressionNone means the payload is uncompressed raw pixels. CompressionNone Compression = 0x00 // CompressionLZ4 uses the LZ4 block compression algorithm. CompressionLZ4 Compression = 0x01 // CompressionZstd uses the Zstandard compression algorithm. CompressionZstd Compression = 0x02 )
func (Compression) String ¶
func (c Compression) String() string
String returns the human-readable name of the compression algorithm.
func (Compression) Valid ¶
func (c Compression) Valid() bool
Valid reports whether c is a known compression algorithm.
type Flag ¶
type Flag uint8
Flag is a bitfield carried in the header's Flags byte.
const ( // FlagDirtyValid indicates that the DirtyRect fields contain valid data. // When not set, the entire frame is considered dirty (keyframe). FlagDirtyValid Flag = 1 << iota // FlagCompressed indicates that the payload is compressed. // The Compression field specifies the algorithm. FlagCompressed // FlagKeyframe marks the frame as a full keyframe (no delta dependency). FlagKeyframe )
type Header ¶
type Header struct {
// Magic is the protocol identifier (must be "COMP").
Magic [4]byte
// Version is the protocol version number.
Version uint16
// MsgType identifies the message kind (Frame, Handshake, Ack, etc.).
MsgType MsgType
// Flags is a bitfield (DirtyValid, Compressed, Keyframe).
Flags Flag
// ModuleID is the compositor-assigned module identifier.
ModuleID uint64
// Sequence is the monotonically increasing frame counter per module.
Sequence uint64
// TimestampNs is the monotonic clock timestamp in nanoseconds.
TimestampNs int64
// Width is the frame width in pixels.
Width uint16
// Height is the frame height in pixels.
Height uint16
// Stride is the number of bytes per row (typically Width * 4).
Stride uint32
// DirtyX is the X offset of the dirty rectangle.
DirtyX uint16
// DirtyY is the Y offset of the dirty rectangle.
DirtyY uint16
// DirtyW is the width of the dirty rectangle.
DirtyW uint16
// DirtyH is the height of the dirty rectangle.
DirtyH uint16
// PixelFormat identifies the pixel encoding (RGBA8, BGRA8).
PixelFormat PixelFormat
// Compression identifies the payload compression algorithm.
Compression Compression
// Reserved is padding for future use. Must be zero.
Reserved [6]byte
// PayloadSize is the number of payload bytes following this header.
PayloadSize uint32
// UncompressedSize is the original payload size before compression.
// When Compression is None, this equals PayloadSize.
UncompressedSize uint32
}
Header is the 64-byte frame header that precedes every message on the wire. All multi-byte fields are little-endian encoded.
type HelloMsg ¶
type HelloMsg struct {
// Magic must be "COMP" (0x43, 0x4F, 0x4D, 0x50).
Magic [4]byte
// Version is the protocol version the module supports.
Version uint16
// Name is the null-terminated human-readable module name (max 63 chars + NUL).
Name [64]byte
// Width is the initial frame width in pixels.
Width uint16
// Height is the initial frame height in pixels.
Height uint16
// PreferredFPS is the module's preferred frame rate (e.g., 1 for clock, 60 for animation).
PreferredFPS uint16
// Transport is the module's preferred transport mechanism.
Transport TransportType
// Reserved is padding for future use. Must be zero.
// Size: 128 - 4 - 2 - 64 - 2 - 2 - 2 - 1 = 51
Reserved [51]byte
}
HelloMsg is sent by the module to the compositor during the handshake phase. Fixed 128 bytes.
Layout: Magic(4) + Version(2) + Name(64) + Width(2) + Height(2) + PreferredFPS(2) + Transport(1) + Reserved(51) = 128
func DecodeHello ¶
DecodeHello reads a HelloMsg from buf and validates the magic bytes. buf must be at least HandshakeSize (128) bytes. Never allocates.
type MsgType ¶
type MsgType uint8
MsgType identifies the kind of message carried by a frame header.
const ( // MsgFrame carries a rendered pixel buffer from module to compositor. MsgFrame MsgType = 0x01 // MsgHandshake is the initial connection negotiation message. MsgHandshake MsgType = 0x02 // MsgAck acknowledges receipt of a frame (compositor to module). MsgAck MsgType = 0x03 // MsgFrameRequest is sent by the compositor to request the next frame // from a module (pull-based flow control, Wayland pattern). MsgFrameRequest MsgType = 0x04 // MsgResize notifies a module that its frame dimensions have changed. MsgResize MsgType = 0x05 // MsgDisconnect signals a graceful disconnection. MsgDisconnect MsgType = 0x06 )
type PixelFormat ¶
type PixelFormat uint8
PixelFormat identifies the pixel encoding of frame payload data.
const ( // PixelRGBA8 is 8-bit RGBA, 4 bytes per pixel, premultiplied alpha. PixelRGBA8 PixelFormat = 0x00 // PixelBGRA8 is 8-bit BGRA, 4 bytes per pixel, premultiplied alpha. // Common on Windows/DX12 surfaces. PixelBGRA8 PixelFormat = 0x01 )
func (PixelFormat) String ¶
func (p PixelFormat) String() string
String returns the human-readable name of the pixel format.
func (PixelFormat) Valid ¶
func (p PixelFormat) Valid() bool
Valid reports whether p is a known pixel format.
type TransportType ¶
type TransportType uint8
TransportType identifies the preferred or granted transport mechanism.
const ( // TransportSocket indicates Unix domain socket transport. TransportSocket TransportType = 0 // TransportShm indicates shared memory transport. TransportShm TransportType = 1 )
func (TransportType) String ¶
func (t TransportType) String() string
String returns the human-readable name of the transport type.
type WelcomeMsg ¶
type WelcomeMsg struct {
// Magic must be "COMP" (0x43, 0x4F, 0x4D, 0x50).
Magic [4]byte
// Version is the protocol version the compositor selected.
Version uint16
// ModuleID is the compositor-assigned unique identifier for this module.
ModuleID uint64
// Accepted is 1 if the connection was accepted, 0 if rejected.
Accepted uint8
// Transport is the transport mechanism the compositor granted.
Transport TransportType
// MinVersion is the minimum protocol version the compositor supports.
MinVersion uint16
// MaxVersion is the maximum protocol version the compositor supports.
MaxVersion uint16
// Reserved is padding for future use. Must be zero.
// Size: 128 - 4 - 2 - 8 - 1 - 1 - 2 - 2 = 108
Reserved [108]byte
}
WelcomeMsg is sent by the compositor to the module after accepting the handshake. Fixed 128 bytes.
Layout: Magic(4) + Version(2) + ModuleID(8) + Accepted(1) + Transport(1) + MinVersion(2) + MaxVersion(2) + Reserved(108) = 128
func DecodeWelcome ¶
func DecodeWelcome(buf []byte) (WelcomeMsg, error)
DecodeWelcome reads a WelcomeMsg from buf and validates the magic bytes. buf must be at least HandshakeSize (128) bytes. Never allocates.
Source Files