Documentation
¶
Overview ¶
Package wlturbo is a Wayland client transport for Go: connection, framing, descriptor passing, object lifecycle and the bootstrap registry. Protocol bindings are generated into the protocol/ packages.
Index ¶
- Constants
- Variables
- func CheckVersion(version, since uint32, request string) error
- func CloseSentFD(fd int) error
- func CreateAnonymousFile(size int64) (fd int, err error)
- func MapMemory(fd int, size int) ([]byte, error)
- func UnmapMemory(data []byte) error
- type Arg
- type BaseProxy
- type Context
- func (c *Context) AllocateID() uint32
- func (c *Context) CheckProxy(proxy Proxy) error
- func (c *Context) Close() error
- func (c *Context) Register(proxy Proxy)
- func (c *Context) Request(r Request, args ...interface{}) error
- func (c *Context) RequestArgs(r Request, args ...Arg) error
- func (c *Context) RunTill(callback Object) error
- func (c *Context) SendDestructor(proxy Proxy, opcode uint32, args ...interface{}) error
- func (c *Context) SendDestructorWithFDs(proxy Proxy, opcode uint32, fds []int, args ...interface{}) error
- func (c *Context) SendRequest(proxy Proxy, opcode uint32, args ...interface{}) error
- func (c *Context) SendRequestWithFDs(proxy Proxy, opcode uint32, fds []int, args ...interface{}) error
- func (c *Context) Unregister(proxy Proxy)
- func (c *Context) UnregisterID(id uint32)
- type Display
- func (d *Display) AllocateID() uint32
- func (d *Display) Close() error
- func (d *Display) Closed() bool
- func (d *Display) Context() *Context
- func (d *Display) Dispatch() error
- func (d *Display) GetRegistry() *Registry
- func (d *Display) ID() uint32
- func (d *Display) RegisterEventSignature(object uint32, opcode uint16, signature string)
- func (d *Display) Registry() *Registry
- func (d *Display) Roundtrip() error
- func (d *Display) SendRequest(objectID uint32, opcode uint16, args ...interface{}) error
- func (d *Display) SendRequestWithFDs(objectID uint32, opcode uint16, fds []int, args ...interface{}) error
- func (d *Display) Sync() (Object, error)
- type DisplayError
- type Event
- func (e *Event) Array() []byte
- func (e *Event) Data() []byte
- func (e *Event) FD() *OwnedFD
- func (e *Event) Fd() uintptr
- func (e *Event) Fixed() Fixed
- func (e *Event) Int32() int32
- func (e *Event) NewID() Proxy
- func (e *Event) Offset() int
- func (e *Event) Proxy() Proxy
- func (e *Event) String() string
- func (e *Event) Uint32() uint32
- type Fixed
- type Global
- type GlobalHandler
- type Object
- type OwnedFD
- type ProtocolError
- type Proxy
- type Registry
- func (r *Registry) AddGlobalHandler(handler RegistryGlobalHandler)
- func (r *Registry) AddGlobalRemoveHandler(handler RegistryGlobalRemoveHandler)
- func (r *Registry) AddHandler(iface string, handler GlobalHandler)
- func (r *Registry) Bind(name uint32, iface string, version uint32, proxy Proxy) error
- func (r *Registry) BindID(name uint32, iface string, version uint32) (uint32, error)
- func (r *Registry) BindNegotiated(iface string, supported uint32, proxy Proxy) (uint32, error)
- func (r *Registry) Dispatch(event *Event)
- func (r *Registry) EventSignature(opcode uint16) (string, bool)
- func (r *Registry) FindGlobal(iface string) (Global, bool)
- func (r *Registry) FindGlobalByName(name uint32) (Global, bool)
- func (r *Registry) GetGlobals() map[uint32]Global
- func (r *Registry) ID() uint32
- type RegistryGlobalEvent
- type RegistryGlobalHandler
- type RegistryGlobalRemoveEvent
- type RegistryGlobalRemoveHandler
- type Request
- type ShmBuffer
- type ShmPool
Constants ¶
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
const ( // HeaderSize is the fixed size of a Wayland message header in bytes. HeaderSize = 8 // DefaultMaxMessageSize bounds a single Wayland message, including its // header. Larger messages are rejected instead of allocating. DefaultMaxMessageSize = 1 << 20 )
Variables ¶
var ( // ErrMalformedFrame reports a message whose header violates the wire // protocol: too short, misaligned, or larger than the accepted maximum. ErrMalformedFrame = errors.New("malformed wayland frame") // ErrUnknownObject reports an event for an object this client never // created or bound. ErrUnknownObject = errors.New("wayland event for unknown object") // ErrUnknownOpcode reports an event opcode the target object cannot receive. ErrUnknownOpcode = errors.New("wayland event with unknown opcode") // ErrDisplayError reports that the compositor sent wl_display.error. ErrDisplayError = errors.New("wayland display error") )
Sentinel errors reported by the transport. Wire-level failures wrap one of them so callers can classify with errors.Is, while ProtocolError carries the offending object, opcode and size.
var ErrGlobalNotFound = errors.New("wlturbo: global not announced")
ErrGlobalNotFound reports that the compositor does not announce a global.
var ErrVersionTooLow = errors.New("wlturbo: request needs a newer object version")
ErrVersionTooLow reports a request the bound object version does not have.
Functions ¶
func CheckVersion ¶ added in v0.3.0
CheckVersion rejects a request introduced in version since when the object's known version is lower. An unknown version (0) is not checked.
func CloseSentFD ¶ added in v0.3.0
CloseSentFD releases a descriptor after a complete successful Wayland send.
func CreateAnonymousFile ¶
CreateAnonymousFile creates an anonymous file for shared memory
Types ¶
type Arg ¶ added in v0.4.0
type Arg struct {
// contains filtered or unexported fields
}
Arg is one typed request argument. It carries native values (no interface boxing), so building and passing Args to Context.RequestArgs does not allocate. The zero Arg is invalid and makes the request fail before any write. Build Args with the ArgXxx constructors.
func ArgFD ¶ added in v0.4.0
func ArgFD() Arg
ArgFD marks a file descriptor position. Descriptors travel out of band in Request.FDs, so it contributes no bytes to the message body.
type BaseProxy ¶
type BaseProxy struct {
// contains filtered or unexported fields
}
BaseProxy provides base implementation for protocol objects
func (*BaseProxy) SetContext ¶
SetContext sets the proxy's context
func (*BaseProxy) SetVersion ¶ added in v0.3.0
SetVersion records the object's protocol version. Registry.Bind sets it for globals and generated requests copy it from parent to child.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context provides a compatibility layer for wl.Context
func NewContext ¶
NewContext creates a new context from a display
func (*Context) AllocateID ¶
AllocateID allocates a new object ID
func (*Context) CheckProxy ¶ added in v0.3.0
CheckProxy rejects stale and foreign proxies before any bytes are written.
func (*Context) Request ¶ added in v0.3.0
Request runs one request with its whole lifecycle: it checks the proxy and version, allocates and registers Child (inheriting the parent's version), sends, and then either closes the sent descriptors or, on error, unregisters Child and leaves the descriptors with the caller. Child must already have this context; it is passed in args at its wire position.
Every argument is boxed into an interface, and a descriptor is a uintptr placeholder that r.FDs is not checked against. Generated bindings use RequestArgs instead, which marshals the same bytes without allocating.
func (*Context) RequestArgs ¶ added in v0.4.0
RequestArgs is Request with typed arguments: same lifecycle, same wire bytes, no per-argument interface boxing. Child, when set, must be passed as an ArgObject at its wire position. The number of ArgFD markers must equal len(r.FDs); a mismatch fails before the child is allocated, the send guard runs or anything is written, and leaves the descriptors with the caller.
func (*Context) SendDestructor ¶ added in v0.3.0
SendDestructor sends a destructor request exactly once. The proxy is claimed (unregistered) under the connection send lock, after marshaling and immediately before the write: concurrent destructors and later requests on the proxy fail without writing. A marshaling error leaves the proxy registered. A write error after the claim leaves the proxy unregistered; such an error means the connection is broken and must be closed.
func (*Context) SendDestructorWithFDs ¶ added in v0.3.0
func (c *Context) SendDestructorWithFDs(proxy Proxy, opcode uint32, fds []int, args ...interface{}) error
SendDestructorWithFDs is SendDestructor for requests carrying FDs. On error the FDs remain owned by the caller.
func (*Context) SendRequest ¶
SendRequest sends a request through the context. The proxy is validated under the connection send lock, so no request reaches the wire after a destructor for the same proxy.
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. On error the FDs remain owned by the caller.
func (*Context) Unregister ¶
Unregister removes a proxy object Only this proxy is removed: a zombie or a newer object that took the ID is left in place.
func (*Context) UnregisterID ¶
UnregisterID removes a proxy object by ID (overloaded for compatibility)
type Display ¶
type Display struct {
// contains filtered or unexported fields
}
Display represents a connection to the Wayland display
func ConnectFromConn ¶ added in v0.3.0
ConnectFromConn attaches to an established Wayland socket and requests its registry.
func (*Display) AllocateID ¶
AllocateID allocates a new object ID (public method)
func (*Display) Close ¶
Close closes the display connection. It is safe to call more than once; later calls are no-ops. After Close, Dispatch returns net.ErrClosed.
func (*Display) Dispatch ¶
Dispatch reads one complete Wayland message and delivers it to the object that owns it.
Read boundaries never define message boundaries: a header split across several reads and several messages arriving in one read are both handled. Dispatch returns net.ErrClosed after Close, a typed ProtocolError for a malformed frame, io.ErrUnexpectedEOF when the peer closes mid-frame, and os.ErrDeadlineExceeded (not sticky) when a read deadline expires.
Event handlers run while Dispatch holds the dispatch lock, so a handler must not call Dispatch or Roundtrip on the same Display: that call deadlocks. Hand work that needs a roundtrip to another goroutine instead.
func (*Display) GetRegistry ¶
GetRegistry returns the registry (compatibility)
func (*Display) RegisterEventSignature ¶ added in v0.3.0
RegisterEventSignature defines a signature for a legacy proxy. Generated proxies supply it themselves and cannot be overridden.
func (*Display) Roundtrip ¶
Roundtrip waits for one wl_display.sync callback. Concurrent event loops must not call Roundtrip while another goroutine dispatches this connection.
func (*Display) SendRequest ¶
SendRequest sends a request to the compositor
type DisplayError ¶ added in v0.2.0
DisplayError is returned when the compositor reports wl_display.error.
func (*DisplayError) Error ¶ added in v0.2.0
func (e *DisplayError) Error() string
func (*DisplayError) Unwrap ¶ added in v0.2.0
func (e *DisplayError) Unwrap() error
Unwrap reports DisplayError as ErrDisplayError.
type Event ¶
Event represents a Wayland protocol event
func (*Event) Data ¶
Data returns the raw event body. It aliases the connection's receive buffer and is only valid until the handler returns; copy it to keep it.
func (*Event) FD ¶ added in v0.3.0
FD transfers ownership of the next descriptor assigned to this event. An unclaimed descriptor is closed when dispatch completes.
type GlobalHandler ¶
GlobalHandler is called when a global is announced
type OwnedFD ¶ added in v0.3.0
type OwnedFD struct {
// contains filtered or unexported fields
}
OwnedFD owns one received descriptor. Close is idempotent; Take transfers ownership to the caller (who must close it). Descriptor zero is valid.
type ProtocolError ¶ added in v0.2.0
ProtocolError describes a wire-level protocol violation.
func (*ProtocolError) Error ¶ added in v0.2.0
func (e *ProtocolError) Error() string
func (*ProtocolError) Unwrap ¶ added in v0.2.0
func (e *ProtocolError) Unwrap() error
Unwrap returns the sentinel error classifying this violation.
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 registers a handler for registry removals.
func (*Registry) AddHandler ¶
func (r *Registry) AddHandler(iface string, handler GlobalHandler)
AddHandler adds a handler for a specific interface, or "*" for every interface. Handlers accumulate; each announced global calls all of them in registration order.
func (*Registry) BindID ¶
BindID binds to a global object and returns just the ID (compatibility method)
func (*Registry) BindNegotiated ¶ added in v0.3.0
BindNegotiated binds the announced global for iface at min(announced version, supported) and returns that version. It returns ErrGlobalNotFound when the global is absent, so callers can decide whether the capability is optional.
func (*Registry) Dispatch ¶ added in v0.3.0
Dispatch handles wl_registry.global and wl_registry.global_remove. The transport has already validated the body against EventSignature.
func (*Registry) EventSignature ¶ added in v0.3.0
EventSignature reports the wl_registry event signatures.
func (*Registry) FindGlobal ¶
FindGlobal finds a global by interface name
func (*Registry) FindGlobalByName ¶
FindGlobalByName finds a global by its name ID
func (*Registry) GetGlobals ¶
GetGlobals returns all announced globals
type RegistryGlobalEvent ¶
RegistryGlobalEvent represents a registry global announcement
type RegistryGlobalHandler ¶
type RegistryGlobalHandler interface {
HandleRegistryGlobal(event RegistryGlobalEvent)
}
RegistryGlobalHandler interface
type RegistryGlobalRemoveEvent ¶
RegistryGlobalRemoveEvent represents a registry global removal
type RegistryGlobalRemoveHandler ¶
type RegistryGlobalRemoveHandler interface {
HandleRegistryGlobalRemove(event RegistryGlobalRemoveEvent)
}
RegistryGlobalRemoveHandler interface
type Request ¶ added in v0.3.0
type Request struct {
Proxy Proxy
Opcode uint32
Name string // interface.request, used in errors
Since uint32 // version that introduced the request; 0 or 1 means always
Destructor bool // claim the proxy exactly once, as SendDestructor does
Child Proxy // new_id object created by this request, or nil
FDs []int // descriptors to attach; closed after a successful send
}
Request describes one protocol request for Context.Request and Context.RequestArgs.
type ShmBuffer ¶
type ShmBuffer struct {
// contains filtered or unexported fields
}
ShmBuffer represents a buffer allocated from a pool
type ShmPool ¶
type ShmPool struct {
// contains filtered or unexported fields
}
ShmPool represents a shared memory pool
func CreateShmPool ¶
CreateShmPool creates a new shared memory pool
func (*ShmPool) AllocateBuffer ¶
AllocateBuffer allocates a buffer from the pool
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
wlturbo-scanner
command
Command wlturbo-scanner generates Go bindings from Wayland protocol XML files.
|
Command wlturbo-scanner generates Go bindings from Wayland protocol XML files. |
|
internal
|
|
|
scanner
Package scanner generates WLTurbo-backed Go bindings from Wayland protocol XML files.
|
Package scanner generates WLTurbo-backed Go bindings from Wayland protocol XML files. |
|
core
Package core contains canonical Wayland core protocol bindings generated from pinned wayland.xml.
|
Package core contains canonical Wayland core protocol bindings generated from pinned wayland.xml. |
|
Package wl provides type aliases for easy migration from neurlang/wayland
|
Package wl provides type aliases for easy migration from neurlang/wayland |