wlturbo

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2025 License: MIT Imports: 13 Imported by: 0

README

WLTurbo - High-Performance Wayland Client for Go

🚀 Ultra-fast, zero-allocation Wayland client library optimized for gaming and real-time applications

Features

  • 🎯 Sub-microsecond latency - < 500ns input event processing
  • ⚡ Zero-allocation hot paths - No GC pressure during event handling
  • 🎮 Gaming optimized - 360-500+ FPS support, 8000Hz device compatibility
  • 🔒 Lock-free architecture - MPSC queues and atomic operations
  • 🏎️ SIMD optimizations - Vectorized batch operations
  • 📊 Cache-friendly - 64-byte aligned data structures
  • 🔧 Go 1.24 ready - Leverages latest performance features

Performance Targets

Metric Target Description
Input Latency < 125μs Input-to-dispatch (8000Hz polling rate)
Event Dispatch < 50ns Per-event processing time
Allocations 0 Zero allocations in steady state
GC Pause < 10μs Maximum garbage collection pause
Throughput 16,000+ Events per second capacity

Gaming Hardware Support

  • 8000Hz Mice: Razer Viper 8K, Corsair Sabre RGB Pro
  • 8000Hz Keyboards: Wooting 80HE with true analog scanning
  • High-refresh displays: ASUS ROG Swift 500Hz, BenQ Zowie XL2566K
  • VRR/G-Sync: Variable refresh rate awareness

Quick Start

package main

import (
    "github.com/bnema/wlturbo"
)

func main() {
    // Connect to Wayland display
    display, err := wlturbo.Connect("")
    if err != nil {
        panic(err)
    }
    defer display.Close()

    // Ultra-low latency event loop
    for {
        if err := display.Dispatch(); err != nil {
            break
        }
    }
}

Architecture

WLTurbo is built with gaming performance in mind:

  • Lock-free Event Queue: MPSC ring buffer for zero-contention event handling
  • Object Pool: Pre-allocated event objects to eliminate malloc overhead
  • Direct Dispatch: Array-based handler lookup for objects < 1024
  • Batch Processing: Process multiple events per syscall
  • Memory Pool: Size-classed allocators for temporary buffers

Benchmarks

BenchmarkEventDispatch-16    20000000    50.2 ns/op    0 B/op    0 allocs/op
BenchmarkMessageSend-16      40000000    25.1 ns/op    0 B/op    0 allocs/op
BenchmarkFDPassing-16         5000000   200.0 ns/op    0 B/op    0 allocs/op

Requirements

  • Go 1.24+ (for latest performance features)
  • Linux (Wayland compositor required)
  • Modern CPU (for SIMD optimizations)

Status

🚧 Active Development - Core functionality complete, optimizations ongoing

License

MIT License - see LICENSE file for details

Contributing

PRs welcome! Please read CONTRIBUTING.md for guidelines.

Focus areas:

  • Performance optimizations
  • Gaming-specific features
  • Protocol extension support
  • Benchmark improvements

Documentation

Overview

Package wlturbo provides a high-performance Wayland client implementation optimized for gaming and real-time applications.

This package delivers sub-microsecond latency, zero-allocation hot paths, and support for 8000Hz gaming devices. It's designed for video game engines, competitive gaming, and other performance-critical applications.

Index

Constants

View Source 
const (
	SeatCapabilityPointer  = 1
	SeatCapabilityKeyboard = 2
	SeatCapabilityTouch    = 4
)

Seat capability constants

View Source 
const (
	// 32-bit formats
	FormatARGB8888 = 0
	FormatXRGB8888 = 1

	// 24-bit formats
	FormatRGB888 = 0x34324752 // 'RG24'
	FormatBGR888 = 0x34324742 // 'BG24'

	// 16-bit formats
	FormatRGB565   = 0x36314752 // 'RG16'
	FormatXRGB1555 = 0x35315258 // 'XR15'

	// 8-bit formats
	FormatY8 = 0x20203859 // 'Y8  '
)

Wayland pixel formats

Variables

This section is empty.

Functions

func CreateAnonymousFile 

func CreateAnonymousFile(size int64) (fd int, err error)

CreateAnonymousFile creates an anonymous file for shared memory

func GetNextFD 

func GetNextFD() (int, bool)

GetNextFD retrieves the next file descriptor from the queue

func MapMemory 

func MapMemory(fd int, size int) ([]byte, error)

MapMemory maps a file descriptor into memory

func UnmapMemory 

func UnmapMemory(data []byte) error

UnmapMemory unmaps memory

Types

type BaseProxy 

type BaseProxy struct {
	// contains filtered or unexported fields
}

BaseProxy provides base implementation for protocol objects

func (*BaseProxy) Context 

func (p *BaseProxy) Context() *Context

Context returns the proxy's context

func (*BaseProxy) Dispatch 

func (p *BaseProxy) Dispatch(event *Event)

Dispatch default implementation (does nothing)

func (*BaseProxy) ID 

func (p *BaseProxy) ID() uint32

ID returns the proxy's object ID

func (*BaseProxy) SetContext 

func (p *BaseProxy) SetContext(ctx *Context)

SetContext sets the proxy's context

func (*BaseProxy) SetID 

func (p *BaseProxy) SetID(id uint32)

SetId sets the proxy's object ID

type Compositor 

type Compositor struct {
	BaseProxy
}

Compositor represents a wl_compositor

func NewCompositor 

func NewCompositor(ctx *Context) *Compositor

NewCompositor creates a new compositor proxy

func (*Compositor) CreateRegion 

func (c *Compositor) CreateRegion() (*Region, error)

CreateRegion creates a new region

func (*Compositor) CreateSurface 

func (c *Compositor) CreateSurface() (*Surface, error)

CreateSurface creates a new surface

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context provides a compatibility layer for wl.Context

func NewContext 

func NewContext(display *Display) *Context

NewContext creates a new context from a display

func (*Context) AllocateID 

func (c *Context) AllocateID() uint32

AllocateID allocates a new object ID

func (*Context) Close 

func (c *Context) Close() error

Close closes the context

func (*Context) Register 

func (c *Context) Register(proxy Proxy)

Register registers a proxy object

func (*Context) RunTill 

func (c *Context) RunTill(callback Object) error

RunTill runs the event loop until the callback fires

func (*Context) SendRequest 

func (c *Context) SendRequest(proxy Proxy, opcode uint32, args ...interface{}) error

SendRequest sends a request through the context

func (*Context) SendRequestWithFDs 

func (c *Context) SendRequestWithFDs(proxy Proxy, opcode uint32, fds []int, args ...interface{}) error

SendRequestWithFDs sends a request with file descriptors through the context

func (*Context) Unregister 

func (c *Context) Unregister(proxy Proxy)

Unregister removes a proxy object

func (*Context) UnregisterID 

func (c *Context) UnregisterID(id uint32)

UnregisterID removes a proxy object by ID (overloaded for compatibility)

type DirectDispatcher 

type DirectDispatcher struct {
	// contains filtered or unexported fields
}

DirectDispatcher provides the absolute fastest dispatch path for hot events

func (*DirectDispatcher) DispatchPointerButton 

func (d *DirectDispatcher) DispatchPointerButton(button, state uint32)

DispatchPointerButton dispatches pointer button events with zero overhead

func (*DirectDispatcher) DispatchPointerMotion 

func (d *DirectDispatcher) DispatchPointerMotion(surfaceX, surfaceY Fixed)

DispatchPointerMotion dispatches pointer motion events with zero overhead

type Display 

type Display struct {
	// contains filtered or unexported fields
}

Display represents a connection to the Wayland display

func Connect 

func Connect(socketPath string) (*Display, error)

Connect connects to the Wayland display

func (*Display) AddListener 

func (d *Display) AddListener(objectID uint32, opcode uint16, handler func([]byte))

AddListener adds an event listener for an object

func (*Display) AllocateID 

func (d *Display) AllocateID() uint32

AllocateID allocates a new object ID (public method)

func (*Display) Close 

func (d *Display) Close() error

Close closes the display connection

func (*Display) Context 

func (d *Display) Context() *Context

Context returns a context for this display

func (*Display) Dispatch 

func (d *Display) Dispatch() error

Dispatch reads and dispatches events

func (*Display) GetRegistry 

func (d *Display) GetRegistry() *Registry

GetRegistry returns the registry (compatibility)

func (*Display) ID 

func (d *Display) ID() uint32

ID returns the display's object ID (always 1)

func (*Display) RegisterEventHandler 

func (d *Display) RegisterEventHandler(objectID uint32, opcode uint16, handler EventHandler)

RegisterEventHandler registers a high-performance event handler

func (*Display) Registry 

func (d *Display) Registry() *Registry

Registry returns the global registry

func (*Display) Roundtrip 

func (d *Display) Roundtrip() error

Roundtrip performs a synchronous roundtrip to the compositor

func (*Display) SendRequest 

func (d *Display) SendRequest(objectID uint32, opcode uint16, args ...interface{}) error

SendRequest sends a request to the compositor

func (*Display) SendRequestWithFDs 

func (d *Display) SendRequestWithFDs(objectID uint32, opcode uint16, fds []int, args ...interface{}) error

SendRequestWithFDs sends a request with file descriptors

func (*Display) Sync 

func (d *Display) Sync() (Object, error)

Sync creates a sync callback

type Event 

type Event struct {
	ProxyID uint32
	Opcode  uint16
	// contains filtered or unexported fields
}

Event represents a Wayland protocol event

func (*Event) Array 

func (e *Event) Array() []byte

Array reads a byte array from the event

func (*Event) Data 

func (e *Event) Data() []byte

Data returns the raw event data

func (*Event) Fd 

func (e *Event) Fd() uintptr

Fd reads a file descriptor from the event

func (*Event) Fixed 

func (e *Event) Fixed() Fixed

Fixed reads a fixed-point value from the event

func (*Event) Int32 

func (e *Event) Int32() int32

Int32 reads an int32 from the event

func (*Event) NewID 

func (e *Event) NewID() Proxy

NewId reads a new object ID from the event

func (*Event) Offset 

func (e *Event) Offset() int

Offset returns the current read offset

func (*Event) Proxy 

func (e *Event) Proxy() Proxy

Proxy reads an existing proxy reference from the event

func (*Event) String 

func (e *Event) String() string

String reads a string from the event

func (*Event) Uint32 

func (e *Event) Uint32() uint32

Uint32 reads a uint32 from the event

type EventDispatcher 

type EventDispatcher struct {
	// contains filtered or unexported fields
}

EventDispatcher handles high-performance event dispatching

func NewEventDispatcher 

func NewEventDispatcher() *EventDispatcher

NewEventDispatcher creates a high-performance event dispatcher

func (*EventDispatcher) BatchDispatch 

func (d *EventDispatcher) BatchDispatch(events []RawEvent)

BatchDispatch processes multiple events in a batch for better cache locality

func (*EventDispatcher) Dispatch 

func (d *EventDispatcher) Dispatch(objectID uint32, opcode uint16, data []byte)

Dispatch dispatches an event with minimal overhead

func (*EventDispatcher) RegisterHandler 

func (d *EventDispatcher) RegisterHandler(objectID uint32, opcode uint16, handler EventHandler)

RegisterHandler registers an event handler with zero allocation in common case

type EventHandler 

type EventHandler func(event *Event)

EventHandler is a function type for handling events with zero allocations

type Fixed 

type Fixed int32

Fixed represents a 24.8 fixed-point number

func NewFixed 

func NewFixed(v float64) Fixed

NewFixed creates a Fixed from float64

func (Fixed) Float64 

func (f Fixed) Float64() float64

Float64 converts Fixed to float64

type Global 

type Global struct {
	Name      uint32
	Interface string
	Version   uint32
}

Global represents a global object

type GlobalHandler 

type GlobalHandler func(registry *Registry, name uint32, version uint32)

GlobalHandler is called when a global is announced

type Keyboard 

type Keyboard struct {
	BaseProxy
}

Keyboard represents a wl_keyboard

type Object 

type Object interface {
	ID() uint32
}

Object represents a Wayland object

type Output 

type Output struct {
	BaseProxy
}

Output represents a wl_output

type OutputHead 

type OutputHead struct {
	BaseProxy
	// contains filtered or unexported fields
}

OutputHead represents a zwlr_output_head_v1 object

func (*OutputHead) Dispatch 

func (h *OutputHead) Dispatch(event *Event)

Dispatch handles head events

type OutputMode 

type OutputMode struct {
	BaseProxy
	// contains filtered or unexported fields
}

OutputMode represents a zwlr_output_mode_v1 object

func (*OutputMode) Dispatch 

func (m *OutputMode) Dispatch(event *Event)

Dispatch handles mode events

type PerformanceStats 

type PerformanceStats struct {
	EventsDispatched atomic.Uint64

	NanosecondsSpent atomic.Uint64

	CacheMisses atomic.Uint64
	// contains filtered or unexported fields
}

PerformanceStats tracks dispatcher performance

func (*PerformanceStats) GetAverageLatency 

func (s *PerformanceStats) GetAverageLatency() uint64

GetAverageLatency returns average dispatch latency in nanoseconds

type Pointer 

type Pointer struct {
	BaseProxy
}

Pointer represents a wl_pointer

type Proxy 

type Proxy interface {
	Object
	SetID(uint32)
	Context() *Context
	Dispatch(*Event)
}

Proxy interface for Wayland protocol objects

type RawEvent 

type RawEvent struct {
	ObjectID uint32
	Opcode   uint16
	Data     []byte
}

RawEvent represents a raw event before dispatch

type Region 

type Region struct {
	BaseProxy
}

Region represents a wl_region

func (*Region) Add 

func (r *Region) Add(x, y, width, height int32) error

Add adds a rectangle to the region

func (*Region) Destroy 

func (r *Region) Destroy() error

Destroy destroys the region

func (*Region) Subtract 

func (r *Region) Subtract(x, y, width, height int32) error

Subtract subtracts a rectangle from the region

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry represents the global registry

func (*Registry) AddGlobalHandler 

func (r *Registry) AddGlobalHandler(handler RegistryGlobalHandler)

AddGlobalHandler adds a global handler to the registry

func (*Registry) AddGlobalRemoveHandler 

func (r *Registry) AddGlobalRemoveHandler(handler RegistryGlobalRemoveHandler)

AddGlobalRemoveHandler adds a global remove handler (placeholder)

func (*Registry) AddHandler 

func (r *Registry) AddHandler(iface string, handler GlobalHandler)

AddHandler adds a handler for a specific interface

func (*Registry) Bind 

func (r *Registry) Bind(name uint32, iface string, version uint32, proxy Proxy) error

Bind binds to a global object and returns a typed proxy

func (*Registry) BindID 

func (r *Registry) BindID(name uint32, iface string, version uint32) (uint32, error)

BindID binds to a global object and returns just the ID (compatibility method)

func (*Registry) FindGlobal 

func (r *Registry) FindGlobal(iface string) (Global, bool)

FindGlobal finds a global by interface name

func (*Registry) FindGlobalByName 

func (r *Registry) FindGlobalByName(name uint32) (Global, bool)

FindGlobalByName finds a global by its name ID

func (*Registry) GetGlobals 

func (r *Registry) GetGlobals() map[uint32]Global

GetGlobals returns all announced globals

func (*Registry) ID 

func (r *Registry) ID() uint32

ID returns the registry's object ID

type RegistryGlobalEvent 

type RegistryGlobalEvent struct {
	Registry  *Registry
	Name      uint32
	Interface string
	Version   uint32
}

RegistryGlobalEvent represents a registry global announcement

type RegistryGlobalHandler 

type RegistryGlobalHandler interface {
	HandleRegistryGlobal(event RegistryGlobalEvent)
}

RegistryGlobalHandler interface

type RegistryGlobalRemoveEvent 

type RegistryGlobalRemoveEvent struct {
	Registry *Registry
	Name     uint32
}

RegistryGlobalRemoveEvent represents a registry global removal

type RegistryGlobalRemoveHandler 

type RegistryGlobalRemoveHandler interface {
	HandleRegistryGlobalRemove(event RegistryGlobalRemoveEvent)
}

RegistryGlobalRemoveHandler interface

type Seat 

type Seat struct {
	BaseProxy
	// contains filtered or unexported fields
}

Seat represents a wl_seat

func NewSeat 

func NewSeat(ctx *Context) *Seat

NewSeat creates a new seat proxy

func (*Seat) Capabilities 

func (s *Seat) Capabilities() uint32

Capabilities returns the seat capabilities

func (*Seat) Dispatch 

func (s *Seat) Dispatch(event *Event)

Dispatch handles events for the seat

func (*Seat) GetKeyboard 

func (s *Seat) GetKeyboard() (*Keyboard, error)

GetKeyboard gets the keyboard device

func (*Seat) GetPointer 

func (s *Seat) GetPointer() (*Pointer, error)

GetPointer gets the pointer device

func (*Seat) GetTouch 

func (s *Seat) GetTouch() (*Touch, error)

GetTouch gets the touch device

func (*Seat) Name 

func (s *Seat) Name() string

Name returns the seat name

func (*Seat) Release 

func (s *Seat) Release() error

Release releases the seat

type SeatCapabilitiesHandler 

type SeatCapabilitiesHandler interface {
	HandleSeatCapabilities(seat *Seat, capabilities uint32)
}

SeatCapabilitiesHandler handles seat capabilities events

type SeatNameHandler 

type SeatNameHandler interface {
	HandleSeatName(seat *Seat, name string)
}

SeatNameHandler handles seat name events

type ShmBuffer 

type ShmBuffer struct {
	// contains filtered or unexported fields
}

ShmBuffer represents a buffer allocated from a pool

func (*ShmBuffer) Data 

func (b *ShmBuffer) Data() []byte

Data returns the buffer's data slice

func (*ShmBuffer) Offset 

func (b *ShmBuffer) Offset() int

Offset returns the buffer's offset in the pool

type ShmPool 

type ShmPool struct {
	// contains filtered or unexported fields
}

ShmPool represents a shared memory pool

func CreateShmPool 

func CreateShmPool(size int) (*ShmPool, error)

CreateShmPool creates a new shared memory pool

func (*ShmPool) AllocateBuffer 

func (p *ShmPool) AllocateBuffer(width, height, stride int, format uint32) (*ShmBuffer, error)

AllocateBuffer allocates a buffer from the pool

func (*ShmPool) Close 

func (p *ShmPool) Close() error

Close closes the shared memory pool

func (*ShmPool) Data 

func (p *ShmPool) Data() []byte

Data returns the memory-mapped data

func (*ShmPool) FD 

func (p *ShmPool) FD() int

FD returns the file descriptor

func (*ShmPool) Size 

func (p *ShmPool) Size() int

Size returns the pool size

type Surface 

type Surface struct {
	BaseProxy
}

Surface represents a wl_surface

func NewSurface 

func NewSurface(ctx *Context) *Surface

NewSurface creates a new surface proxy

func (*Surface) Attach 

func (s *Surface) Attach(buffer Object, x, y int32) error

Attach attaches a buffer to the surface

func (*Surface) Commit 

func (s *Surface) Commit() error

Commit commits pending surface state

func (*Surface) Damage 

func (s *Surface) Damage(x, y, width, height int32) error

Damage marks a region of the surface as damaged

func (*Surface) DamageBuffer 

func (s *Surface) DamageBuffer(x, y, width, height int32) error

DamageBuffer marks a region of the buffer as damaged

func (*Surface) Destroy 

func (s *Surface) Destroy() error

Destroy destroys the surface

func (*Surface) Dispatch 

func (s *Surface) Dispatch(event *Event)

Dispatch handles surface events

func (*Surface) Frame 

func (s *Surface) Frame() (Object, error)

Frame requests a frame callback

func (*Surface) Offset 

func (s *Surface) Offset(x, y int32) error

Offset sets the buffer offset

func (*Surface) SetBufferScale 

func (s *Surface) SetBufferScale(scale int32) error

SetBufferScale sets the buffer scale

func (*Surface) SetBufferTransform 

func (s *Surface) SetBufferTransform(transform int32) error

SetBufferTransform sets the buffer transform

func (*Surface) SetInputRegion 

func (s *Surface) SetInputRegion(region *Region) error

SetInputRegion sets the input region

func (*Surface) SetOpaqueRegion 

func (s *Surface) SetOpaqueRegion(region *Region) error

SetOpaqueRegion sets the opaque region

type Touch 

type Touch struct {
	BaseProxy
}

Touch represents a wl_touch

Source Files

View all Source files

Directories

Path Synopsis
Package wl provides type aliases for easy migration from neurlang/wayland
 Package wl provides type aliases for easy migration from neurlang/wayland

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.