Canonical core / migration (v0.x)
protocol/core replaces root-package and wl shim core object types. Bootstrap
Display, Registry, Context, and BaseProxy remain in the root/wl
transport. Bind globals using core.NewCompositor(display.Context()),
core.NewSeat(display.Context()), etc. and display.Registry().Bind(name, core.CompositorInterface, version, compositor). Requests create typed registered
children (seat.GetKeyboard(), surface.Frame(), shm.CreatePool()) and
server-side new_id events register concrete objects before invoking handlers.
Do not overwrite registered objects with a second wrapper.
Breaking changes: wlturbo/wl Seat, Surface, Pointer, Keyboard,
Touch, Output, Region, Compositor, their constructors, and seat
capability aliases have moved to protocol/core. Generated methods accept
concrete core objects and return concrete children, not wl.Object. Legacy
raw Event.Fd() is not for generated events; generated FD handlers receive
*wlturbo.OwnedFD with Take() (int,error) or Close(); second and later
handlers receive nil FD. On a successful full send a generated FD request
closes the local descriptor; on error the caller keeps it. Registry.BindID
remains for legacy callers but cannot register typed event dispatch: prefer
Bind and generated constructors. Unrecognized custom-proxy event opcodes
now fail unless declared via Display.RegisterEventSignature.
The scanner accepts -import wl_surface=github.com/bnema/wlturbo/protocol/core
(repeat for each external type); local XML definitions take precedence, then
explicit external mapping, then only bootstrap display/registry. Generate with
GOWORK=off go generate ./...; metadata and XML license are in
protocol/SOURCE.md. Extension packages under protocol/ use the same scanner
and public core mappings; the generator carries no compositor policy.
Generated requests use Context.RequestArgs with typed Arg values to avoid
boxing numeric arguments. Custom proxies may use the same API; Context.Request
and the raw send methods remain available. Both request APIs share version,
child-object, destructor and descriptor lifecycle handling. Strings and arrays
passed as arguments are borrowed until the synchronous request returns.
For client code in compositor tests, replace handwritten protocol proxies with
these generated constructors and typed handlers. Keep compositor-side server
implementations in the compositor repository. Negotiate optional globals and
handle their absence rather than testing the compositor's name.
source
1# Canonical core / migration (v0.x)
2
3`protocol/core` replaces root-package and `wl` shim core object types. Bootstrap
4`Display`, `Registry`, `Context`, and `BaseProxy` remain in the root/`wl`
5transport. Bind globals using `core.NewCompositor(display.Context())`,
6`core.NewSeat(display.Context())`, etc. and `display.Registry().Bind(name,
7core.CompositorInterface, version, compositor)`. Requests create typed registered
8children (`seat.GetKeyboard()`, `surface.Frame()`, `shm.CreatePool()`) and
9server-side `new_id` events register concrete objects before invoking handlers.
10Do not overwrite registered objects with a second wrapper.
11
12Breaking changes: `wlturbo`/`wl` `Seat`, `Surface`, `Pointer`, `Keyboard`,
13`Touch`, `Output`, `Region`, `Compositor`, their constructors, and seat
14capability aliases have moved to `protocol/core`. Generated methods accept
15concrete core objects and return concrete children, not `wl.Object`. Legacy
16raw `Event.Fd()` is not for generated events; generated FD handlers receive
17`*wlturbo.OwnedFD` with `Take() (int,error)` or `Close()`; second and later
18handlers receive nil FD. On a successful full send a generated FD request
19closes the local descriptor; on error the caller keeps it. `Registry.BindID`
20remains for legacy callers but cannot register typed event dispatch: prefer
21`Bind` and generated constructors. Unrecognized custom-proxy event opcodes
22now fail unless declared via `Display.RegisterEventSignature`.
23
24The scanner accepts `-import wl_surface=github.com/bnema/wlturbo/protocol/core`
25(repeat for each external type); local XML definitions take precedence, then
26explicit external mapping, then only bootstrap display/registry. Generate with
27`GOWORK=off go generate ./...`; metadata and XML license are in
28`protocol/SOURCE.md`. Extension packages under `protocol/` use the same scanner
29and public core mappings; the generator carries no compositor policy.
30
31Generated requests use `Context.RequestArgs` with typed `Arg` values to avoid
32boxing numeric arguments. Custom proxies may use the same API; `Context.Request`
33and the raw send methods remain available. Both request APIs share version,
34child-object, destructor and descriptor lifecycle handling. Strings and arrays
35passed as arguments are borrowed until the synchronous request returns.
36
37For client code in compositor tests, replace handwritten protocol proxies with
38these generated constructors and typed handlers. Keep compositor-side server
39implementations in the compositor repository. Negotiate optional globals and
40handle their absence rather than testing the compositor's name.