rfb-encodings

RFB (Remote Framebuffer) protocol encoding implementations for VNC.

Support this project:

3QVD3H1ryqyxhuf8hNTTuBXSbczNuAKaM8

0xaFE28A1Dd57660610Ef46C05EfAA363356e98DC7

6uWx4wuHERBpNxyWjeQKrMLBVte91aBzkHaJb8rhw4rn

8C5aCs7Api3WE67GMw54AhQKnJsCg6CVffCuPxUcaKoiMrnaicyvDch8M2CXTm1DJqhpHKxtLvum9Thw4yHn8zeu7sj8qmC

This crate provides encoding implementations for the VNC/RFB protocol, including all standard encodings defined in RFC 6143. It can be used to build VNC servers, clients, proxies, or recorders.

Supported Encodings

All 10 encodings have automated tests. See Testing for details.

Features

• Pure Rust - Memory-safe implementation with no unsafe code
• RFC 6143 Compliant - Follows the official RFB protocol specification
• Persistent Streams - Maintains zlib compression state for better compression ratios
• Pixel Format Translation - Supports all VNC pixel formats (8/16/24/32-bit)
• Optional TurboJPEG - Hardware-accelerated JPEG compression via feature flag

Usage

Add this to your Cargo.toml:

[dependencies]
rfb-encodings = "0.1"

Basic Example

use rfb_encodings::{Encoding, TightEncoding, PixelFormat};

// Create encoder
let encoder = TightEncoding;

// Encode RGBA pixel data
let rgba_data: Vec<u8> = vec![/* your pixel data */];
let width = 1920;
let height = 1080;
let quality = 9;  // 0-9, higher is better quality
let compression = 6;  // 0-9, higher is more compression

let encoded = encoder.encode(&rgba_data, width, height, quality, compression);

Advanced Usage with Persistent Streams

For better compression with Tight encoding:

use rfb_encodings::{
    encode_tight_rects, SimpleTightCompressor, PixelFormat
};

let mut compressor = SimpleTightCompressor::new(6);
let client_format = PixelFormat::rgba32();

let rectangles = encode_tight_rects(
    &rgba_data,
    width,
    height,
    9,  // quality
    6,  // compression
    &client_format,
    &mut compressor
);

// Returns Vec<(x, y, width, height, encoded_data)>
for (x, y, w, h, data) in rectangles {
    // Send rectangle to VNC client
}

Features

• turbojpeg - Enable TurboJPEG for hardware-accelerated JPEG compression in Tight encoding
• debug-logging - Enable verbose debug logging for troubleshooting

Enable features in your Cargo.toml:

[dependencies]
rfb-encodings = { version = "0.1", features = ["turbojpeg", "debug-logging"] }

TurboJPEG Installation

The turbojpeg feature requires libjpeg-turbo to be installed on your system:

Ubuntu/Debian:

sudo apt-get install libturbojpeg0-dev

macOS:

brew install jpeg-turbo

Windows: Download from libjpeg-turbo.org

Architecture

This crate is designed to be reusable across different VNC implementations:

• encoding modules - Individual encoder implementations
• PixelFormat - VNC pixel format definition and utilities
• translate - Pixel format translation between different color depths
• TightStreamCompressor trait - Interface for persistent zlib streams

Third-Party Dependencies

Optional: libjpeg-turbo (TurboJPEG)

When using the turbojpeg feature, this crate provides FFI bindings to libjpeg-turbo, which must be installed separately on your system. libjpeg-turbo is licensed under a BSD-style license (BSD-3-Clause, IJG, and zlib components).

License Information:

• libjpeg-turbo: BSD-3-Clause, IJG License, zlib License
• Note: You are responsible for ensuring compliance with libjpeg-turbo's license terms when using the turbojpeg feature.

License

This crate is licensed under the Apache License, Version 2.0. See LICENSE for details.

The turbojpeg feature provides optional bindings to libjpeg-turbo, which is licensed separately. See above for details.

Testing

This crate includes comprehensive tests for all 10 encodings:

# First: generate test fixtures (required once)
# Creates deterministic RGBA test images in tests/fixtures/
#   - frame_64x64.rgba: 4-quadrant pattern (gradient, solid, checkerboard)
#   - frame_100x75.rgba: non-64-aligned image to test ZRLE bug fix
cargo run --bin generate_fixture

# Then: generate golden files for your platform (required once per OS)
# Encodes fixtures and saves output to tests/expected/{linux,macos,windows}/
cargo test --test golden_tests --features generate-golden

# Run all tests
cargo test

Test Types

Cross-Platform Notes

• Golden files must be generated per-OS: Zlib compression can produce different (but equally valid) output on different platforms. Run with --features generate-golden on each platform to create tests/expected/{linux,macos,windows}/
• Endian-aware decoders: Test decoders handle both big-endian and little-endian pixel formats

Test Coverage

• 44 total tests across unit tests, decoder tests, and golden tests
• 8 unit tests for ZRLE buffer handling and pixel translation
• 3 decoder tests for the test decoder implementations
• 33 golden/round-trip tests covering all 10 encodings

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.