detached d5c3b4c

feat(scanner): port Wayland XML generator and pin core protocol source

commit
d5c3b4c24b23fa49a5ca03e6b65c6e3f5ecf405d
author
brice · · 2026-09-28 07:14 UTC
parent
ab733e5
signature
GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email
8 files · +4596 -0
Unified
UnifiedSplit
A cmd/wlturbo-scanner/main.go +132 -0
@@ -0,0 +1,132 @@
1+// Command wlturbo-scanner generates Go bindings from Wayland protocol XML files.
2+//
3+// Usage:
4+//
5+// wlturbo-scanner [flags] protocol.xml
6+//
7+// Flags:
8+//
9+// -o, --output Output file path (default: <protocol>_generated.go)
10+// -p, --package Go package name (default: derived from protocol name)
11+// -h, --help Show help
12+//
13+// Examples:
14+//
15+// # Generate bindings for virtual pointer protocol
16+// wlturbo-scanner -o virtual_pointer.go ../wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml
17+//
18+// # Generate with custom package name
19+// wlturbo-scanner -p vpointer -o vpointer.go protocol.xml
20+package main
21+
22+import (
23+ "flag"
24+ "fmt"
25+ "log"
26+ "os"
27+ "path/filepath"
28+ "strings"
29+
30+ "github.com/bnema/wlturbo/internal/scanner"
31+)
32+
33+func main() {
34+ var (
35+ outputPath string
36+ packageName string
37+ showHelp bool
38+ crossImports crossFlags
39+ )
40+
41+ flag.StringVar(&outputPath, "o", "", "Output file path")
42+ flag.StringVar(&outputPath, "output", "", "Output file path")
43+ flag.StringVar(&packageName, "p", "", "Go package name")
44+ flag.StringVar(&packageName, "package", "", "Go package name")
45+ flag.Var(&crossImports, "import", "Interface=Go import path (repeatable)")
46+ flag.BoolVar(&showHelp, "h", false, "Show help")
47+ flag.BoolVar(&showHelp, "help", false, "Show help")
48+
49+ flag.Usage = func() {
50+ fmt.Fprintf(os.Stderr, "Usage: %s [flags] protocol.xml\n\n", os.Args[0])
51+ fmt.Fprintf(os.Stderr, "Generates Go bindings from Wayland protocol XML files.\n\n")
52+ fmt.Fprintf(os.Stderr, "Flags:\n")
53+ flag.PrintDefaults()
54+ fmt.Fprintf(os.Stderr, "\nExamples:\n")
55+ fmt.Fprintf(os.Stderr, " # Generate bindings for virtual pointer protocol\n")
56+ fmt.Fprintf(os.Stderr, " %s -o virtual_pointer.go wlr-virtual-pointer-unstable-v1.xml\n\n", os.Args[0])
57+ fmt.Fprintf(os.Stderr, " # Generate with custom package name\n")
58+ fmt.Fprintf(os.Stderr, " %s -p vpointer -o vpointer.go protocol.xml\n", os.Args[0])
59+ }
60+
61+ flag.Parse()
62+
63+ if showHelp || flag.NArg() == 0 {
64+ flag.Usage()
65+ if showHelp {
66+ os.Exit(0)
67+ }
68+ os.Exit(1)
69+ }
70+
71+ xmlPath := flag.Arg(0)
72+
73+ // Derive output path if not specified
74+ if outputPath == "" {
75+ base := filepath.Base(xmlPath)
76+ base = strings.TrimSuffix(base, filepath.Ext(base))
77+ outputPath = base + "_generated.go"
78+ }
79+
80+ // Derive package name if not specified
81+ if packageName == "" {
82+ base := filepath.Base(xmlPath)
83+ base = strings.TrimSuffix(base, filepath.Ext(base))
84+
85+ // Clean up common prefixes/suffixes
86+ base = strings.TrimPrefix(base, "wlr-")
87+ base = strings.TrimPrefix(base, "zwlr-")
88+ base = strings.TrimSuffix(base, "-unstable-v1")
89+ base = strings.TrimSuffix(base, "-unstable-v2")
90+ base = strings.TrimSuffix(base, "-stable-v1")
91+
92+ // Convert to valid Go package name
93+ packageName = strings.ReplaceAll(base, "-", "_")
94+ }
95+
96+ // Create scanner
97+ s := scanner.NewScanner()
98+ s.CrossPackage = crossImports
99+
100+ // Parse XML
101+ if err := s.ParseXML(xmlPath); err != nil {
102+ log.Fatalf("Failed to parse XML: %v", err)
103+ }
104+
105+ // Generate code
106+ code, err := s.Generate(packageName)
107+ if err != nil {
108+ log.Fatalf("Failed to generate code: %v", err)
109+ }
110+
111+ // Write output with secure permissions
112+ if err := os.WriteFile(outputPath, code, 0600); err != nil {
113+ log.Fatalf("Failed to write output: %v", err)
114+ }
115+
116+ fmt.Printf("Generated %s (package %s)\n", outputPath, packageName)
117+}
118+
119+type crossFlags map[string]string
120+
121+func (f *crossFlags) String() string { return fmt.Sprint(map[string]string(*f)) }
122+func (f *crossFlags) Set(v string) error {
123+ parts := strings.SplitN(v, "=", 2)
124+ if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
125+ return fmt.Errorf("-import must be interface=GoImportPath")
126+ }
127+ if *f == nil {
128+ *f = make(map[string]string)
129+ }
130+ (*f)[parts[0]] = parts[1]
131+ return nil
132+}
A internal/scanner/scanner.go +714 -0
@@ -0,0 +1,714 @@
1+// Package scanner generates WLTurbo-backed Go bindings from Wayland protocol
2+// XML files.
3+//
4+// The generated code owns protocol semantics only: it embeds wl.BaseProxy,
5+// allocates and registers child objects through the wl.Context, sends requests
6+// through that context, and dispatches typed events to registered handlers.
7+// Message framing, descriptor passing and connection lifetime stay in the
8+// transport, so a generated binding never opens a socket or writes a header.
9+package scanner
10+
11+import (
12+ "bytes"
13+ "encoding/xml"
14+ "fmt"
15+ "go/format"
16+ "io"
17+ "os"
18+ "path/filepath"
19+ "sort"
20+ "strings"
21+ "text/template"
22+)
23+
24+// TransportImport is the import path generated bindings use for the Wayland
25+// transport.
26+const TransportImport = "github.com/bnema/wlturbo/wl"
27+
28+// Protocol represents a Wayland protocol specification
29+type Protocol struct {
30+ XMLName xml.Name `xml:"protocol"`
31+ Name string `xml:"name,attr"`
32+ Copyright string `xml:"copyright"`
33+ Description *Description `xml:"description"`
34+ Interfaces []Interface `xml:"interface"`
35+}
36+
37+// Interface represents a Wayland interface in the protocol
38+type Interface struct {
39+ Name string `xml:"name,attr"`
40+ Version int `xml:"version,attr"`
41+ Description *Description `xml:"description"`
42+ Requests []Request `xml:"request"`
43+ Events []Event `xml:"event"`
44+ Enums []Enum `xml:"enum"`
45+}
46+
47+// Request represents a client-to-server message
48+type Request struct {
49+ Name string `xml:"name,attr"`
50+ Type string `xml:"type,attr"` // "destructor" or empty
51+ Since int `xml:"since,attr"`
52+ Description *Description `xml:"description"`
53+ Args []Arg `xml:"arg"`
54+}
55+
56+// Event represents a server-to-client message
57+type Event struct {
58+ Type string `xml:"type,attr"`
59+ Name string `xml:"name,attr"`
60+ Since int `xml:"since,attr"`
61+ Description *Description `xml:"description"`
62+ Args []Arg `xml:"arg"`
63+}
64+
65+// Arg represents a message argument
66+type Arg struct {
67+ Name string `xml:"name,attr"`
68+ Type string `xml:"type,attr"`
69+ Summary string `xml:"summary,attr"`
70+ Interface string `xml:"interface,attr"`
71+ AllowNull bool `xml:"allow-null,attr"`
72+ Enum string `xml:"enum,attr"`
73+}
74+
75+// Enum represents an enumeration type
76+type Enum struct {
77+ Name string `xml:"name,attr"`
78+ Since int `xml:"since,attr"`
79+ Bitfield bool `xml:"bitfield,attr"`
80+ Description *Description `xml:"description"`
81+ Entries []Entry `xml:"entry"`
82+}
83+
84+// Entry represents an enum value
85+type Entry struct {
86+ Name string `xml:"name,attr"`
87+ Value string `xml:"value,attr"`
88+ Summary string `xml:"summary,attr"`
89+ Since int `xml:"since,attr"`
90+}
91+
92+// Description represents documentation
93+type Description struct {
94+ Summary string `xml:"summary,attr"`
95+ Text string `xml:",chardata"`
96+}
97+
98+// Scanner generates Go bindings from Wayland protocol XML
99+type Scanner struct {
100+ protocol *Protocol
101+ source string
102+ // CrossPackage maps interface names to Go package import paths. Local wins.
103+ CrossPackage map[string]string
104+}
105+
106+// NewScanner creates a new protocol scanner
107+func NewScanner() *Scanner {
108+ return &Scanner{}
109+}
110+
111+// ParseXML parses a Wayland protocol XML file
112+func (s *Scanner) ParseXML(path string) error {
113+ file, err := os.Open(path)
114+ if err != nil {
115+ return fmt.Errorf("failed to open XML file: %w", err)
116+ }
117+ defer func() { _ = file.Close() }()
118+
119+ data, err := io.ReadAll(file)
120+ if err != nil {
121+ return fmt.Errorf("failed to read XML file: %w", err)
122+ }
123+
124+ var protocol Protocol
125+ if err := xml.Unmarshal(data, &protocol); err != nil {
126+ return fmt.Errorf("failed to parse XML: %w", err)
127+ }
128+
129+ s.protocol = &protocol
130+ // Only the base name is recorded: generated output must not depend on the
131+ // path the XML happened to be read from.
132+ s.source = filepath.Base(path)
133+ return nil
134+}
135+
136+// Generate creates Go source code for the parsed protocol
137+func (s *Scanner) Generate(packageName string) ([]byte, error) {
138+ if s.protocol == nil {
139+ return nil, fmt.Errorf("no protocol parsed")
140+ }
141+
142+ data, err := s.prepareTemplateData(packageName)
143+ if err != nil {
144+ return nil, err
145+ }
146+
147+ var buf bytes.Buffer
148+ tmpl := template.Must(template.New("protocol").Parse(protocolTemplate))
149+ if err := tmpl.Execute(&buf, data); err != nil {
150+ return nil, fmt.Errorf("failed to execute template: %w", err)
151+ }
152+
153+ formatted, err := format.Source(buf.Bytes())
154+ if err != nil {
155+ return buf.Bytes(), fmt.Errorf("failed to format generated code: %w", err)
156+ }
157+ return formatted, nil
158+}
159+
160+// templateData holds data for template generation
161+type templateData struct {
162+ Package string
163+ Protocol string
164+ Source string
165+ ImportBlock string
166+ Constants []constantData
167+ Interfaces []interfaceData
168+}
169+
170+type interfaceData struct {
171+ Name string
172+ GoName string
173+ Version int
174+ HasEvents bool
175+ SignatureCases []signatureCase
176+ Requests []requestData
177+ Events []eventData
178+}
179+
180+type signatureCase struct {
181+ Opcode int
182+ Signature string
183+}
184+type requestData struct {
185+ Name string
186+ GoName string
187+ Doc string
188+ Opcode int
189+ Destructor bool
190+ Params string
191+ Results string
192+ ArgPreparations []string
193+ ArgExprs []string
194+ CreatesChild bool
195+ ChildVar string
196+ ChildType string
197+ ErrorReturn string
198+ FDArgs []string
199+ HasFDs bool
200+ SendCall string
201+}
202+
203+// argSlot is one positional argument of a request, in declaration order. A
204+// new_id slot is filled in once the child object has been created.
205+type argSlot struct {
206+ newID bool
207+ expr string
208+}
209+
210+type eventData struct {
211+ HasFD bool
212+ ServerDestroy bool
213+ FDNames []string
214+ Name string
215+ GoName string
216+ Opcode int
217+ HandlerField string
218+ HandlerAccessor string
219+ HandlerParams string
220+ HandlerArgs string
221+ DecodeLines []string
222+}
223+
224+type constantData struct {
225+ Name string
226+ Value string
227+ Type string
228+ Enum string
229+ Entry string
230+}
231+
232+// Only display and registry have handwritten bootstrap bindings.
233+var bootstrapTypes = map[string]bool{
234+ "Display": true,
235+ "Registry": true,
236+}
237+
238+// goKeywords are avoided as parameter names because generated identifiers
239+// must not collide with the language.
240+var goKeywords = map[string]bool{
241+ "break": true, "case": true, "chan": true, "const": true, "continue": true,
242+ "default": true, "defer": true, "else": true, "fallthrough": true, "for": true,
243+ "func": true, "go": true, "goto": true, "if": true, "import": true,
244+ "interface": true, "map": true, "package": true, "range": true, "return": true,
245+ "select": true, "struct": true, "switch": true, "type": true, "var": true,
246+}
247+
248+func (s *Scanner) prepareTemplateData(packageName string) (templateData, error) {
249+ data := templateData{
250+ Package: packageName,
251+ Protocol: s.protocol.Name,
252+ Source: s.source,
253+ }
254+
255+ imports := []string{TransportImport}
256+ usedCross := make(map[string]bool)
257+ for _, candidate := range s.protocol.Interfaces {
258+ for _, req := range candidate.Requests {
259+ for _, arg := range req.Args {
260+ if arg.Type == "object" || arg.Type == "new_id" {
261+ usedCross[arg.Interface] = true
262+ }
263+ }
264+ }
265+ for _, ev := range candidate.Events {
266+ for _, arg := range ev.Args {
267+ if arg.Type == "object" || arg.Type == "new_id" {
268+ usedCross[arg.Interface] = true
269+ }
270+ }
271+ }
272+ }
273+ for iface, path := range s.CrossPackage {
274+ local := false
275+ for _, candidate := range s.protocol.Interfaces {
276+ if candidate.Name == iface {
277+ local = true
278+ break
279+ }
280+ }
281+ if local || !usedCross[iface] || bootstrapTypes[s.toGoName(iface)] {
282+ continue
283+ }
284+ alias := "cross_" + strings.ReplaceAll(iface, "-", "_")
285+ imports = append(imports, alias+" "+path)
286+ }
287+ sort.Strings(imports)
288+ stdImports := []string{}
289+ needsSync := false
290+
291+ // Enum constants are package-level declarations, so two interfaces that
292+ // declare the same enum entry (for example xdg_surface.error.invalid_size
293+ // and xdg_toplevel.error.invalid_size) would collide. Entries whose name
294+ // occurs in more than one interface are qualified with their interface
295+ // name below; unique names keep their historical, unprefixed form.
296+ enumEntryCounts := map[string]int{}
297+ for _, iface := range s.protocol.Interfaces {
298+ for _, enum := range iface.Enums {
299+ for _, entry := range enum.Entries {
300+ enumEntryCounts[constantName(enum.Name, entry.Name)]++
301+ }
302+ }
303+ }
304+
305+ for _, iface := range s.protocol.Interfaces {
306+ if packageName == "core" && (iface.Name == "wl_display" || iface.Name == "wl_registry") {
307+ continue
308+ }
309+ ifaceData, err := s.processInterface(iface)
310+ if err != nil {
311+ return data, err
312+ }
313+ data.Interfaces = append(data.Interfaces, ifaceData)
314+ if len(iface.Events) > 0 {
315+ needsSync = true
316+ }
317+
318+ for _, enum := range iface.Enums {
319+ for _, entry := range enum.Entries {
320+ name := constantName(enum.Name, entry.Name)
321+ if enumEntryCounts[name] > 1 {
322+ name = qualifiedConstantName(iface.Name, enum.Name, entry.Name)
323+ }
324+ // Enum values are emitted untyped: the same enum travels as a uint
325+ // in one protocol and as an int in another, and an untyped constant
326+ // assigns to either without casts at the call site.
327+ data.Constants = append(data.Constants, constantData{
328+ Name: name,
329+ Value: entry.Value,
330+ Enum: enum.Name,
331+ Entry: entry.Name,
332+ })
333+ }
334+ }
335+ }
336+
337+ // Handlers are registered and dispatched from different goroutines, so an
338+ // interface with events needs a mutex.
339+ if needsSync {
340+ stdImports = append(stdImports, "sync")
341+ }
342+
343+ var block strings.Builder
344+ block.WriteString("import (\n")
345+ for _, imp := range stdImports {
346+ fmt.Fprintf(&block, "\t%q\n", imp)
347+ }
348+ if len(stdImports) > 0 && len(imports) > 0 {
349+ block.WriteString("\n")
350+ }
351+ for _, imp := range imports {
352+ if strings.Contains(imp, " ") {
353+ parts := strings.SplitN(imp, " ", 2)
354+ fmt.Fprintf(&block, "\t%s %q\n", parts[0], parts[1])
355+ } else {
356+ fmt.Fprintf(&block, "\t%q\n", imp)
357+ }
358+ }
359+ block.WriteString(")")
360+ data.ImportBlock = block.String()
361+
362+ return data, nil
363+}
364+
365+func (s *Scanner) processInterface(iface Interface) (interfaceData, error) {
366+ data := interfaceData{
367+ Name: iface.Name,
368+ GoName: s.toGoName(iface.Name),
369+ Version: iface.Version,
370+ HasEvents: len(iface.Events) > 0,
371+ }
372+
373+ for i, req := range iface.Requests {
374+ request, err := s.processRequest(iface, req, i)
375+ if err != nil {
376+ return data, err
377+ }
378+ data.Requests = append(data.Requests, request)
379+ }
380+
381+ for i, event := range iface.Events {
382+ var sig strings.Builder
383+ for _, arg := range event.Args {
384+ sig.WriteString(arg.Type)
385+ sig.WriteByte(',')
386+ }
387+ data.SignatureCases = append(data.SignatureCases, signatureCase{i, sig.String()})
388+ eventData, err := s.processEvent(event, i)
389+ if iface.Name == "wl_callback" && event.Name == "done" {
390+ eventData.ServerDestroy = true
391+ }
392+ if err != nil {
393+ return data, err
394+ }
395+ data.Events = append(data.Events, eventData)
396+ }
397+
398+ return data, nil
399+}
400+
401+func (s *Scanner) processRequest(iface Interface, req Request, opcode int) (requestData, error) {
402+ data := requestData{
403+ Name: req.Name,
404+ GoName: s.toGoName(req.Name),
405+ Doc: s.formatDescription(req.Description),
406+ Opcode: opcode,
407+ Destructor: req.Type == "destructor",
408+ ChildVar: "child",
409+ }
410+
411+ var (
412+ params []string
413+ argSlots []argSlot
414+ argExprs []string
415+ fdExprs []string
416+ newIDArg *Arg
417+ )
418+
419+ for i, arg := range req.Args {
420+ if arg.Type == "new_id" {
421+ if newIDArg != nil {
422+ return data, fmt.Errorf("%s.%s: more than one new_id argument is not supported", iface.Name, req.Name)
423+ }
424+ newIDArg = &arg
425+ // The child object is created later, but it keeps its declared
426+ // position: the wire order is the argument order.
427+ argSlots = append(argSlots, argSlot{newID: true})
428+ continue
429+ }
430+
431+ name := s.paramName(arg.Name, i)
432+ goType, err := s.goTypeForArg(arg)
433+ if err != nil {
434+ return data, fmt.Errorf("%s.%s: %w", iface.Name, req.Name, err)
435+ }
436+
437+ expr := name
438+ switch arg.Type {
439+ case "object":
440+ // Objects are pointer types, and travel as wl.Object so a nil
441+ // pointer is never sent as a non-nil interface holding a typed nil.
442+ params = append(params, name+" *"+goType)
443+ holder := fmt.Sprintf("arg%d", i)
444+ data.ArgPreparations = append(data.ArgPreparations,
445+ fmt.Sprintf("var %s wl.Object", holder),
446+ fmt.Sprintf("if %s != nil {", name),
447+ fmt.Sprintf("\t%s = %s", holder, name),
448+ "}")
449+ expr = holder
450+
451+ case "fd":
452+ // Descriptors travel out of band: the body carries no value for
453+ // them, and the descriptor list is attached to the request.
454+ params = append(params, name+" int")
455+ fdExprs = append(fdExprs, name)
456+ data.FDArgs = append(data.FDArgs, name)
457+ expr = "uintptr(" + name + ")"
458+
459+ default:
460+ params = append(params, name+" "+goType)
461+ }
462+
463+ argSlots = append(argSlots, argSlot{expr: expr})
464+ }
465+
466+ if newIDArg != nil {
467+ childType, err := s.goTypeForArg(*newIDArg)
468+ if err != nil {
469+ return data, fmt.Errorf("%s.%s: %w", iface.Name, req.Name, err)
470+ }
471+ data.CreatesChild = true
472+ data.ChildType = childType
473+ }
474+
475+ for _, slot := range argSlots {
476+ if slot.newID {
477+ argExprs = append(argExprs, data.ChildVar)
478+ continue
479+ }
480+ argExprs = append(argExprs, slot.expr)
481+ }
482+
483+ data.Params = strings.Join(params, ", ")
484+ data.ArgExprs = argExprs
485+ args := ""
486+ if len(argExprs) > 0 {
487+ args = ", " + strings.Join(argExprs, ", ")
488+ }
489+ if len(fdExprs) > 0 {
490+ data.HasFDs = true
491+ data.SendCall = fmt.Sprintf("SendRequestWithFDs(o, %d, []int{%s}%s)", opcode, strings.Join(fdExprs, ", "), args)
492+ } else {
493+ data.SendCall = fmt.Sprintf("SendRequest(o, %d%s)", opcode, args)
494+ }
495+ if data.CreatesChild {
496+ data.Results = "(*" + data.ChildType + ", error)"
497+ data.ErrorReturn = "nil, err"
498+ } else {
499+ data.Results = "error"
500+ data.ErrorReturn = "err"
501+ }
502+
503+ return data, nil
504+}
505+
506+func (s *Scanner) processEvent(event Event, opcode int) (eventData, error) {
507+ goName := s.toGoName(event.Name)
508+ data := eventData{
509+ ServerDestroy: event.Type == "destructor",
510+ Name: event.Name,
511+ GoName: goName,
512+ Opcode: opcode,
513+ HandlerField: "on" + goName,
514+ HandlerAccessor: "handlersFor" + goName,
515+ }
516+
517+ var params, args []string
518+
519+ for i, arg := range event.Args {
520+ name := s.paramName(arg.Name, i)
521+
522+ switch arg.Type {
523+ case "new_id":
524+ childType, err := s.goTypeForArg(arg)
525+ if err != nil {
526+ return data, fmt.Errorf("%s.%s: %w", event.Name, arg.Name, err)
527+ }
528+ child := name + "Object"
529+ data.DecodeLines = append(data.DecodeLines,
530+ fmt.Sprintf("%sID := event.Uint32()", name),
531+ fmt.Sprintf("%s := &%s{}", child, childType),
532+ fmt.Sprintf("%s.SetContext(o.Context())", child),
533+ fmt.Sprintf("%s.SetID(%sID)", child, name),
534+ fmt.Sprintf("o.Context().Register(%s)", child),
535+ )
536+ params = append(params, child+" *"+childType)
537+ args = append(args, child)
538+
539+ case "object":
540+ // Object references are reported as raw object IDs: the generated
541+ // layer does not own a registry of foreign proxies.
542+ data.DecodeLines = append(data.DecodeLines, fmt.Sprintf("%sID := event.Uint32()", name))
543+ params = append(params, name+"ID uint32")
544+ args = append(args, name+"ID")
545+
546+ default:
547+ if arg.Type == "fd" {
548+ data.HasFD = true
549+ data.FDNames = append(data.FDNames, name)
550+ }
551+ goType, decoder, err := s.scalarDecoder(arg)
552+ if err != nil {
553+ return data, fmt.Errorf("%s.%s: %w", event.Name, arg.Name, err)
554+ }
555+ data.DecodeLines = append(data.DecodeLines, fmt.Sprintf("%s := event.%s()", name, decoder))
556+ params = append(params, name+" "+goType)
557+ args = append(args, name)
558+ }
559+ }
560+
561+ data.HandlerParams = strings.Join(params, ", ")
562+ data.HandlerArgs = strings.Join(args, ", ")
563+ return data, nil
564+}
565+
566+// scalarDecoder maps a simple argument to its Go type and event decoder.
567+func (s *Scanner) scalarDecoder(arg Arg) (goType, decoder string, err error) {
568+ switch arg.Type {
569+ case "int":
570+ return "int32", "Int32", nil
571+ case "uint":
572+ return "uint32", "Uint32", nil
573+ case "fixed":
574+ return "wl.Fixed", "Fixed", nil
575+ case "string":
576+ return "string", "String", nil
577+ case "array":
578+ return "[]byte", "Array", nil
579+ case "fd":
580+ return "*wl.OwnedFD", "FD", nil
581+ }
582+ return "", "", fmt.Errorf("unsupported event argument type %q", arg.Type)
583+}
584+
585+// goTypeForArg returns the Go type of an object-like argument. Protocol-local
586+// interfaces map to generated types, explicit external references to their
587+// mapped package, and bootstrap display/registry to transport wrappers.
588+func (s *Scanner) goTypeForArg(arg Arg) (string, error) {
589+ switch arg.Type {
590+ case "int":
591+ return "int32", nil
592+ case "uint":
593+ return "uint32", nil
594+ case "fixed":
595+ return "wl.Fixed", nil
596+ case "string":
597+ return "string", nil
598+ case "array":
599+ return "[]byte", nil
600+ case "fd":
601+ return "int", nil
602+ case "object", "new_id":
603+ return s.goTypeForInterface(arg.Interface), nil
604+ }
605+ return "", fmt.Errorf("unsupported argument type %q", arg.Type)
606+}
607+
608+func (s *Scanner) goTypeForInterface(iface string) string {
609+ if iface == "" {
610+ return "wl.BaseProxy"
611+ }
612+ // The XML package owns its own definitions even when the name starts wl_.
613+ for _, local := range s.protocol.Interfaces {
614+ if local.Name == iface && iface != "wl_display" && iface != "wl_registry" {
615+ return s.toGoName(iface)
616+ }
617+ }
618+ if bootstrapTypes[s.toGoName(iface)] {
619+ return "wl." + s.toGoName(iface)
620+ }
621+ if _, ok := s.CrossPackage[iface]; ok {
622+ return "cross_" + strings.ReplaceAll(iface, "-", "_") + "." + s.toGoName(iface)
623+ }
624+ return "wl.BaseProxy"
625+}
626+
627+// paramName turns a protocol argument name into a Go parameter name.
628+func (s *Scanner) paramName(name string, index int) string {
629+ if name == "" {
630+ return fmt.Sprintf("arg%d", index)
631+ }
632+
633+ parts := strings.Split(name, "_")
634+ for i, part := range parts {
635+ if part == "" {
636+ continue
637+ }
638+ if i == 0 {
639+ parts[i] = strings.ToLower(part[:1]) + part[1:]
640+ continue
641+ }
642+ parts[i] = strings.ToUpper(part[:1]) + part[1:]
643+ }
644+ result := strings.Join(parts, "")
645+ if result == "" {
646+ return fmt.Sprintf("arg%d", index)
647+ }
648+ if goKeywords[result] {
649+ return result + "Arg"
650+ }
651+ return result
652+}
653+
654+func (s *Scanner) toGoName(name string) string {
655+ name = strings.TrimPrefix(name, "zwlr_")
656+ name = strings.TrimPrefix(name, "zwp_")
657+ name = strings.TrimPrefix(name, "wl_")
658+ name = strings.TrimSuffix(name, "_v1")
659+ name = strings.TrimSuffix(name, "_v2")
660+
661+ parts := strings.Split(name, "_")
662+ for i, part := range parts {
663+ if part != "" {
664+ parts[i] = strings.ToUpper(part[:1]) + part[1:]
665+ }
666+ }
667+ return strings.Join(parts, "")
668+}
669+
670+// constantName renders an enum entry as the unprefixed constant name.
671+func constantName(enum, entry string) string {
672+ return strings.Join(append(joinName(enum), joinName(entry)...), "_")
673+}
674+
675+// qualifiedConstantName prefixes an enum entry constant with its interface
676+// name. It is used for entries that several interfaces declare, which would
677+// otherwise collide in the generated package.
678+func qualifiedConstantName(iface, enum, entry string) string {
679+ return strings.Join(append(joinName(iface), constantName(enum, entry)), "_")
680+}
681+
682+// joinName upper-cases the underscore-separated parts of a protocol name.
683+func joinName(value string) []string {
684+ parts := strings.Split(value, "_")
685+ out := make([]string, 0, len(parts))
686+ for _, part := range parts {
687+ if part != "" {
688+ out = append(out, strings.ToUpper(part))
689+ }
690+ }
691+ return out
692+}
693+
694+// formatDescription renders an argument or request description as a single
695+// documentation line.
696+func (s *Scanner) formatDescription(desc *Description) string {
697+ if desc == nil {
698+ return ""
699+ }
700+
701+ text := strings.TrimSpace(desc.Text)
702+ if text == "" {
703+ return desc.Summary
704+ }
705+
706+ lines := strings.Split(text, "\n")
707+ formatted := make([]string, 0, len(lines))
708+ for _, line := range lines {
709+ if line = strings.TrimSpace(line); line != "" {
710+ formatted = append(formatted, line)
711+ }
712+ }
713+ return strings.Join(formatted, " ")
714+}
A internal/scanner/scanner_test.go +47 -0
@@ -0,0 +1,47 @@
1+package scanner
2+
3+import (
4+ "os"
5+ "path/filepath"
6+ "strings"
7+ "testing"
8+)
9+
10+func TestResolution(t *testing.T) {
11+ p := filepath.Join(t.TempDir(), "fixture.xml")
12+ xml := `<protocol name="sample"><interface name="wl_surface" version="1"><event name="done"><arg name="value" type="uint"/></event></interface><interface name="custom_thing" version="1"><request name="make"><arg name="id" type="new_id" interface="wl_surface"/><arg name="output" type="object" interface="wl_output"/></request></interface></protocol>`
13+ if err := os.WriteFile(p, []byte(xml), 0600); err != nil {
14+ t.Fatal(err)
15+ }
16+ s := NewScanner()
17+ if err := s.ParseXML(p); err != nil {
18+ t.Fatal(err)
19+ }
20+ s.CrossPackage = map[string]string{"wl_surface": "github.com/bnema/wlturbo/protocol/core", "wl_output": "github.com/bnema/wlturbo/protocol/core"}
21+ b, err := s.Generate("fixture")
22+ if err != nil {
23+ t.Fatal(err)
24+ }
25+ text := string(b)
26+ if !strings.Contains(text, "(*Surface, error)") || !strings.Contains(text, "output *cross_wl_output.Output") || strings.Contains(text, "cross_wl_surface") {
27+ t.Fatalf("wrong resolution: %s", text)
28+ }
29+}
30+func TestCoreGeneration(t *testing.T) {
31+ s := NewScanner()
32+ if err := s.ParseXML("../../protocol/wayland.xml"); err != nil {
33+ t.Fatal(err)
34+ }
35+ b, err := s.Generate("core")
36+ if err != nil {
37+ t.Fatal(err)
38+ }
39+ for _, want := range []string{"type Keyboard struct", "type Subsurface struct", "type Buffer struct", "type Callback struct", "return \"uint,fd,uint,\", true", "child := &Keyboard{}"} {
40+ if !strings.Contains(string(b), want) {
41+ t.Errorf("missing %s", want)
42+ }
43+ }
44+ if strings.Contains(string(b), "type Display struct") || strings.Contains(string(b), "type Registry struct") {
45+ t.Fatal("bootstrap generated twice")
46+ }
47+}
A internal/scanner/template.go +139 -0
@@ -0,0 +1,139 @@
1+package scanner
2+
3+// protocolTemplate is the template for generating WLTurbo-backed Go bindings.
4+//
5+// Generated objects embed wl.BaseProxy, allocate and register child objects
6+// through the wl.Context, send requests through that context, and dispatch
7+// typed events to registered handlers. Nothing in the generated code opens a
8+// socket or frames messages itself: that is the transport's job.
9+const protocolTemplate = `// Code generated by wlturbo-scanner. DO NOT EDIT.
10+// Protocol: {{.Protocol}}
11+// Source: {{.Source}}
12+
13+package {{.Package}}
14+
15+{{.ImportBlock}}
16+
17+{{range .Constants}}
18+// {{.Name}} is the {{.Enum}} {{.Entry}} value.
19+const {{.Name}}{{if .Type}} {{.Type}}{{end}} = {{.Value}}
20+{{- end}}
21+{{range .Interfaces}}
22+{{- $iface := .}}
23+
24+// {{$iface.GoName}}Interface is the protocol interface name.
25+const {{$iface.GoName}}Interface = "{{$iface.Name}}"
26+
27+// {{$iface.GoName}} is the generated binding for {{$iface.Name}} version {{$iface.Version}}.
28+type {{$iface.GoName}} struct {
29+ wl.BaseProxy
30+{{- if $iface.HasEvents}}
31+ // handlersMu guards the handler slices: a client may register or replace
32+ // handlers while another goroutine dispatches events.
33+ handlersMu sync.Mutex
34+{{- end}}
35+{{- range $iface.Events}}
36+ {{.HandlerField}} []func({{.HandlerParams}})
37+{{- end}}
38+}
39+
40+// New{{$iface.GoName}} returns an unbound {{$iface.GoName}}.
41+func New{{$iface.GoName}}(ctx *wl.Context) *{{$iface.GoName}} {
42+ obj := &{{$iface.GoName}}{}
43+ obj.SetContext(ctx)
44+ ctx.Register(obj)
45+ return obj
46+}
47+{{- range $iface.Requests}}
48+
49+{{- if .Doc}}
50+// {{.Doc}}
51+{{- end}}
52+func (o *{{$iface.GoName}}) {{.GoName}}({{.Params}}) {{.Results}} {
53+{{- range .ArgPreparations}}
54+ {{.}}
55+{{- end}}
56+{{- if .CreatesChild}}
57+ {{.ChildVar}} := &{{.ChildType}}{}
58+ {{.ChildVar}}.SetContext(o.Context())
59+ {{.ChildVar}}.SetID(o.Context().AllocateID())
60+ o.Context().Register({{.ChildVar}})
61+{{- end}}
62+ if err := o.Context().{{.SendCall}}; err != nil {
63+{{- if .CreatesChild}}
64+ o.Context().Unregister({{.ChildVar}})
65+{{- end}}
66+ return {{.ErrorReturn}}
67+ }
68+{{- range .FDArgs}}
69+ _ = wl.CloseSentFD({{.}})
70+{{- end}}
71+{{- if .Destructor}}
72+ o.Context().Unregister(o)
73+{{- end}}
74+{{- if .CreatesChild}}
75+ return {{.ChildVar}}, nil
76+{{- else}}
77+ return nil
78+{{- end}}
79+}
80+{{- end}}
81+{{- range $iface.Events}}
82+
83+// On{{.GoName}} registers a handler for the {{.Name}} event.
84+//
85+// Handlers are appended, so a second call adds another handler rather than
86+// replacing the first. Registration is safe while another goroutine dispatches.
87+func (o *{{$iface.GoName}}) On{{.GoName}}(handler func({{.HandlerParams}})) {
88+ if handler == nil { return }
89+ o.handlersMu.Lock()
90+ defer o.handlersMu.Unlock()
91+ o.{{.HandlerField}} = append(o.{{.HandlerField}}, handler)
92+}
93+
94+// {{.HandlerAccessor}} returns the handlers registered for {{.Name}}, taken
95+// under the lock so a handler may register another handler while events are
96+// being dispatched.
97+func (o *{{$iface.GoName}}) {{.HandlerAccessor}}() []func({{.HandlerParams}}) {
98+ o.handlersMu.Lock()
99+ defer o.handlersMu.Unlock()
100+ return o.{{.HandlerField}}
101+}
102+{{- end}}
103+
104+// EventSignature returns the declared event argument types in wire order.
105+func (o *{{$iface.GoName}}) EventSignature(opcode uint16) (string, bool) {
106+ switch opcode {
107+ {{- range $iface.SignatureCases}}
108+ case {{.Opcode}}: return "{{.Signature}}", true
109+ {{- end}}
110+ default: return "", false
111+ }
112+}
113+
114+// Dispatch decodes one event on {{$iface.Name}} and calls the registered handlers.
115+func (o *{{$iface.GoName}}) Dispatch(event *wl.Event) {
116+ switch event.Opcode {
117+{{- range $iface.Events}}
118+ case {{.Opcode}}: // {{.Name}}
119+{{- range .DecodeLines}}
120+ {{.}}
121+{{- end}}
122+ {{if .HasFD}}defer func(){ {{range .FDNames}}_ = {{.}}.Close(); {{end}} }(){{end}}
123+ for i, handler := range o.{{.HandlerAccessor}}() {
124+ {{- if .HasFD}}
125+ if i > 0 { {{range .FDNames}}{{.}} = nil; {{end}} }
126+ {{- else}}
127+ _ = i
128+ {{- end}}
129+ handler({{.HandlerArgs}})
130+ }
131+{{- if .ServerDestroy}}
132+ o.Context().Unregister(o)
133+{{- end}}
134+{{- end}}
135+ default:
136+ }
137+}
138+{{end}}
139+`
A internal/scanner/testdata/protocol_fixture.xml +112 -0
@@ -0,0 +1,112 @@
1+<?xml version="1.0" encoding="UTF-8"?>
2+<protocol name="wlvision_fixture">
3+ <copyright>
4+ Synthetic protocol used to test the wlvision protocol generator. It exists
5+ only in this repository's tests.
6+ </copyright>
7+
8+ <interface name="zwlr_fixture_manager_v1" version="2">
9+ <description summary="fixture manager">
10+ Exercises new_id requests, object references, fixed point numbers,
11+ strings, arrays, file descriptors and destructors.
12+ </description>
13+
14+ <request name="create_thing">
15+ <description summary="create a fixture object"/>
16+ <arg name="seat" type="object" interface="wl_seat"/>
17+ <arg name="id" type="new_id" interface="zwlr_fixture_thing_v1"/>
18+ </request>
19+
20+ <request name="set_ratio">
21+ <arg name="ratio" type="fixed"/>
22+ </request>
23+
24+ <request name="set_label">
25+ <arg name="label" type="string"/>
26+ </request>
27+
28+ <request name="set_region">
29+ <arg name="region" type="object" interface="wl_region"/>
30+ </request>
31+
32+ <request name="set_buffer">
33+ <description summary="reference an interface without a typed wrapper"/>
34+ <arg name="buffer" type="object" interface="wl_buffer"/>
35+ </request>
36+
37+ <request name="set_optional_output">
38+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
39+ </request>
40+
41+ <request name="attach_raw">
42+ <arg name="data" type="array"/>
43+ </request>
44+
45+ <request name="pass_fd">
46+ <arg name="fd" type="fd"/>
47+ </request>
48+
49+ <request name="destroy" type="destructor">
50+ <description summary="destroy the manager"/>
51+ </request>
52+
53+ <request name="create_labeled_thing">
54+ <description summary="new_id argument that is not the last one"/>
55+ <arg name="id" type="new_id" interface="zwlr_fixture_thing_v1"/>
56+ <arg name="label" type="string"/>
57+ <arg name="ratio" type="fixed"/>
58+ </request>
59+ </interface>
60+
61+ <interface name="zwlr_fixture_thing_v1" version="1">
62+ <description summary="fixture object"/>
63+
64+ <enum name="fixture_state">
65+ <entry name="idle" value="0"/>
66+ <entry name="busy" value="1"/>
67+ </enum>
68+
69+ <request name="set_scale">
70+ <arg name="scale" type="fixed"/>
71+ </request>
72+
73+ <request name="destroy" type="destructor"/>
74+
75+ <event name="ready">
76+ <arg name="serial" type="uint"/>
77+ </event>
78+
79+ <event name="label_changed">
80+ <arg name="label" type="string"/>
81+ </event>
82+
83+ <event name="geometry">
84+ <arg name="x" type="int"/>
85+ <arg name="y" type="int"/>
86+ <arg name="width" type="uint"/>
87+ <arg name="height" type="uint"/>
88+ </event>
89+
90+ <event name="mode">
91+ <arg name="mode" type="new_id" interface="zwlr_fixture_mode_v1"/>
92+ </event>
93+
94+ <event name="peer">
95+ <arg name="surface" type="object" interface="wl_surface"/>
96+ </event>
97+
98+ <event name="scaled">
99+ <arg name="scale" type="fixed"/>
100+ </event>
101+
102+ <event name="blob">
103+ <arg name="data" type="array"/>
104+ </event>
105+ </interface>
106+
107+ <interface name="zwlr_fixture_mode_v1" version="1">
108+ <description summary="fixture mode object"/>
109+
110+ <request name="destroy" type="destructor"/>
111+ </interface>
112+</protocol>
A protocol/SOURCE.md +7 -0
@@ -0,0 +1,7 @@
1+# Core protocol source
2+
3+`wayland.xml` is from Wayland 1.26.0, upstream GitLab
4+`https://gitlab.freedesktop.org/wayland/wayland`, tag `1.26.0`, peeled commit
5+`87cc8a8728a923fc57938faa81ba0e74f34ecdc7`.
6+SHA-256: `cc860987e54f8d85c940e97fa1270c69b6e4ad31fbcf5a7f00107ce1157f5e07`.
7+License: MIT (full copyright and grant in `wayland.xml` `<copyright>`).
A protocol/generate.go +3 -0
@@ -0,0 +1,3 @@
1+package protocol
2+
3+//go:generate go run ../cmd/wlturbo-scanner -p core -o core/wayland_generated.go wayland.xml
A protocol/wayland.xml +3442 -0
@@ -0,0 +1,3442 @@
1+<?xml version="1.0" encoding="UTF-8"?>
2+<protocol name="wayland">
3+
4+ <copyright>
5+ Copyright © 2008-2011 Kristian Høgsberg
6+ Copyright © 2010-2011 Intel Corporation
7+ Copyright © 2012-2013 Collabora, Ltd.
8+
9+ Permission is hereby granted, free of charge, to any person
10+ obtaining a copy of this software and associated documentation files
11+ (the "Software"), to deal in the Software without restriction,
12+ including without limitation the rights to use, copy, modify, merge,
13+ publish, distribute, sublicense, and/or sell copies of the Software,
14+ and to permit persons to whom the Software is furnished to do so,
15+ subject to the following conditions:
16+
17+ The above copyright notice and this permission notice (including the
18+ next paragraph) shall be included in all copies or substantial
19+ portions of the Software.
20+
21+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
25+ BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
26+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
27+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28+ SOFTWARE.
29+ </copyright>
30+
31+ <interface name="wl_display" version="1">
32+ <description summary="core global object">
33+ The core global object. This is a special singleton object. It
34+ is used for internal Wayland protocol features.
35+ </description>
36+
37+ <request name="sync">
38+ <description summary="asynchronous roundtrip">
39+ The sync request asks the server to emit the 'done' event
40+ on the returned wl_callback object. Since requests are
41+ handled in-order and events are delivered in-order, this can
42+ be used as a barrier to ensure all previous requests and the
43+ resulting events have been handled.
44+
45+ The object returned by this request will be destroyed by the
46+ compositor after the callback is fired and as such the client must not
47+ attempt to use it after that point.
48+
49+ The callback_data passed in the callback is undefined and should be ignored.
50+ </description>
51+ <arg name="callback" type="new_id" interface="wl_callback"
52+ summary="callback object for the sync request"/>
53+ </request>
54+
55+ <request name="get_registry">
56+ <description summary="get global registry object">
57+ This request creates a registry object that allows the client
58+ to list and bind the global objects available from the
59+ compositor.
60+
61+ It should be noted that the server side resources consumed in
62+ response to a get_registry request can only be released when the
63+ client disconnects, not when the client side proxy is destroyed.
64+ Therefore, clients should invoke get_registry as infrequently as
65+ possible to avoid wasting memory.
66+ </description>
67+ <arg name="registry" type="new_id" interface="wl_registry"
68+ summary="global registry object"/>
69+ </request>
70+
71+ <event name="error">
72+ <description summary="fatal error event">
73+ The error event is sent out when a fatal (non-recoverable)
74+ error has occurred. The object_id argument is the object
75+ where the error occurred, most often in response to a request
76+ to that object. The code identifies the error and is defined
77+ by the object interface. As such, each interface defines its
78+ own set of error codes. The message is a brief description
79+ of the error, for (debugging) convenience.
80+ </description>
81+ <arg name="object_id" type="object" summary="object where the error occurred"/>
82+ <arg name="code" type="uint" summary="error code"/>
83+ <arg name="message" type="string" summary="error description"/>
84+ </event>
85+
86+ <enum name="error">
87+ <description summary="global error values">
88+ These errors are global and can be emitted in response to any
89+ server request.
90+ </description>
91+ <entry name="invalid_object" value="0"
92+ summary="server couldn't find object"/>
93+ <entry name="invalid_method" value="1"
94+ summary="method doesn't exist on the specified interface or malformed request"/>
95+ <entry name="no_memory" value="2"
96+ summary="server is out of memory"/>
97+ <entry name="implementation" value="3"
98+ summary="implementation error in compositor"/>
99+ </enum>
100+
101+ <event name="delete_id">
102+ <description summary="acknowledge object ID deletion">
103+ This event is used internally by the object ID management logic.
104+
105+ When the server stops using an object created by the client, the server
106+ sends this event. In particular, after sending this event, the server
107+ will no longer send any events that contain the object as the receiver
108+ or as an argument.
109+
110+ When the client receives this event, it knows that it can reuse the
111+ object ID.
112+ </description>
113+ <arg name="id" type="uint" summary="deleted object ID"/>
114+ </event>
115+ </interface>
116+
117+ <interface name="wl_registry" version="1">
118+ <description summary="global registry object">
119+ The singleton global registry object. The server has a number of
120+ global objects that are available to all clients. These objects
121+ typically represent an actual object in the server (for example,
122+ an input device) or they are singleton objects that provide
123+ extension functionality.
124+
125+ When a client creates a registry object, the registry object
126+ will emit a global event for each global currently in the
127+ registry. Globals come and go as a result of device or
128+ monitor hotplugs, reconfiguration or other events, and the
129+ registry will send out global and global_remove events to
130+ keep the client up to date with the changes. To mark the end
131+ of the initial burst of events, the client can use the
132+ wl_display.sync request immediately after calling
133+ wl_display.get_registry.
134+
135+ A client can bind to a global object by using the bind
136+ request. This creates a client-side handle that lets the object
137+ emit events to the client and lets the client invoke requests on
138+ the object.
139+ </description>
140+
141+ <request name="bind">
142+ <description summary="bind an object to the display">
143+ Binds a new, client-created object to the server using the
144+ specified name as the identifier.
145+ </description>
146+ <arg name="name" type="uint" summary="unique numeric name of the object"/>
147+ <arg name="id" type="new_id" summary="bound object"/>
148+ </request>
149+
150+ <event name="global">
151+ <description summary="announce global object">
152+ Notify the client of global objects.
153+
154+ The event notifies the client that a global object with
155+ the given name is now available, and it implements the
156+ given version of the given interface.
157+ </description>
158+ <arg name="name" type="uint" summary="numeric name of the global object"/>
159+ <arg name="interface" type="string" summary="interface implemented by the object"/>
160+ <arg name="version" type="uint" summary="interface version"/>
161+ </event>
162+
163+ <event name="global_remove">
164+ <description summary="announce removal of global object">
165+ Notify the client of removed global objects.
166+
167+ This event notifies the client that the global identified
168+ by name is no longer available. If the client bound to
169+ the global using the bind request, the client should now
170+ destroy that object.
171+
172+ The object remains valid and requests to the object will be
173+ ignored until the client destroys it, to avoid races between
174+ the global going away and a client sending a request to it.
175+ </description>
176+ <arg name="name" type="uint" summary="numeric name of the global object"/>
177+ </event>
178+ </interface>
179+
180+ <interface name="wl_callback" version="1" frozen="true">
181+ <description summary="callback object">
182+ Clients can handle the 'done' event to get notified when
183+ the related request is done.
184+
185+ Note, because wl_callback objects are created from multiple independent
186+ factory interfaces, the wl_callback interface is frozen at version 1.
187+ </description>
188+
189+ <event name="done" type="destructor">
190+ <description summary="done event">
191+ Notify the client when the related request is done.
192+ </description>
193+ <arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
194+ </event>
195+ </interface>
196+
197+ <interface name="wl_compositor" version="7">
198+ <description summary="the compositor singleton">
199+ A compositor. This object is a singleton global. The
200+ compositor is in charge of combining the contents of multiple
201+ surfaces into one displayable output.
202+ </description>
203+
204+ <request name="create_surface">
205+ <description summary="create new surface">
206+ Ask the compositor to create a new surface.
207+ </description>
208+ <arg name="id" type="new_id" interface="wl_surface" summary="the new surface"/>
209+ </request>
210+
211+ <request name="create_region">
212+ <description summary="create new region">
213+ Ask the compositor to create a new region.
214+ </description>
215+ <arg name="id" type="new_id" interface="wl_region" summary="the new region"/>
216+ </request>
217+
218+ <!-- Version 7 additions -->
219+
220+ <request name="release" type="destructor" since="7">
221+ <description summary="destroy wl_compositor">
222+ This request destroys the wl_compositor. This has no effect on any other objects.
223+ </description>
224+ </request>
225+ </interface>
226+
227+ <interface name="wl_shm_pool" version="3">
228+ <description summary="a shared memory pool">
229+ The wl_shm_pool object encapsulates a piece of memory shared
230+ between the compositor and client. Through the wl_shm_pool
231+ object, the client can allocate shared memory wl_buffer objects.
232+ All objects created through the same pool share the same
233+ underlying mapped memory. Reusing the mapped memory avoids the
234+ setup/teardown overhead and is useful when interactively resizing
235+ a surface or for many small buffers.
236+ </description>
237+
238+ <enum name="error" since="3">
239+ <description summary="wl_shm_pool error values">
240+ These errors can be emitted in response to wl_shm_pool requests.
241+ </description>
242+ <entry name="invalid_format" value="0" summary="buffer format is not known"/>
243+ <entry name="invalid_stride" value="1" summary="invalid size or stride during buffer creation"/>
244+ </enum>
245+
246+ <request name="create_buffer">
247+ <description summary="create a buffer from the pool">
248+ Create a wl_buffer object from the pool.
249+
250+ The buffer is created offset bytes into the pool and has
251+ width and height as specified. The stride argument specifies
252+ the number of bytes from the beginning of one row to the beginning
253+ of the next. The format is the pixel format of the buffer and
254+ must be one of those advertised through the wl_shm.format event.
255+
256+ A buffer will keep a reference to the pool it was created from
257+ so it is valid to destroy the pool immediately after creating
258+ a buffer from it.
259+ </description>
260+ <arg name="id" type="new_id" interface="wl_buffer" summary="buffer to create"/>
261+ <arg name="offset" type="int" summary="buffer byte offset within the pool"/>
262+ <arg name="width" type="int" summary="buffer width, in pixels"/>
263+ <arg name="height" type="int" summary="buffer height, in pixels"/>
264+ <arg name="stride" type="int" summary="number of bytes from the beginning of one row to the beginning of the next row"/>
265+ <arg name="format" type="uint" enum="wl_shm.format" summary="buffer pixel format"/>
266+ </request>
267+
268+ <request name="destroy" type="destructor">
269+ <description summary="destroy the pool">
270+ Destroy the shared memory pool.
271+
272+ The mmapped memory will be released when all
273+ buffers that have been created from this pool
274+ are gone.
275+ </description>
276+ </request>
277+
278+ <request name="resize">
279+ <description summary="change the size of the pool mapping">
280+ This request will cause the server to remap the backing memory
281+ for the pool from the file descriptor passed when the pool was
282+ created, but using the new size. This request can only be
283+ used to make the pool bigger.
284+
285+ This request only changes the amount of bytes that are mmapped
286+ by the server and does not touch the file corresponding to the
287+ file descriptor passed at creation time. It is the client's
288+ responsibility to ensure that the file is at least as big as
289+ the new pool size.
290+ </description>
291+ <arg name="size" type="int" summary="new size of the pool, in bytes"/>
292+ </request>
293+ </interface>
294+
295+ <interface name="wl_shm" version="3">
296+ <description summary="shared memory support">
297+ A singleton global object that provides support for shared
298+ memory.
299+
300+ Clients can create wl_shm_pool objects using the create_pool
301+ request.
302+
303+ On binding the wl_shm object one or more format events
304+ are emitted to inform clients about the valid pixel formats
305+ that can be used for buffers.
306+ </description>
307+
308+ <enum name="error" since="3">
309+ <description summary="wl_shm error values">
310+ These errors can be emitted in response to wl_shm requests.
311+ </description>
312+ <entry name="invalid_format" value="0" summary="buffer format is not known" deprecated-since="3"/>
313+ <entry name="invalid_stride" value="1" summary="invalid size or stride during pool creation"/>
314+ <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
315+ </enum>
316+
317+ <enum name="format">
318+ <description summary="pixel formats">
319+ This describes the memory layout of an individual pixel.
320+
321+ All renderers should support argb8888 and xrgb8888 but any other
322+ formats are optional and may not be supported by the particular
323+ renderer in use.
324+
325+ The drm format codes match the macros defined in drm_fourcc.h, except
326+ argb8888 and xrgb8888. The formats actually supported by the compositor
327+ will be reported by the format event. See drm_fourcc.h for more detailed
328+ format descriptions.
329+
330+ For all wl_shm formats and unless specified in another protocol
331+ extension, pre-multiplied alpha is used for pixel values.
332+ </description>
333+ <!-- Note to protocol writers: don't update this list manually, instead
334+ run the automated script that keeps it in sync with drm_fourcc.h. -->
335+ <entry name="argb8888" value="0" summary="32-bit ARGB format, [31:0] A:R:G:B 8:8:8:8 little endian"/>
336+ <entry name="xrgb8888" value="1" summary="32-bit RGB format, [31:0] x:R:G:B 8:8:8:8 little endian"/>
337+ <entry name="c8" value="0x20203843" summary="8-bit color index format, [7:0] C"/>
338+ <entry name="rgb332" value="0x38424752" summary="8-bit RGB format, [7:0] R:G:B 3:3:2"/>
339+ <entry name="bgr233" value="0x38524742" summary="8-bit BGR format, [7:0] B:G:R 2:3:3"/>
340+ <entry name="xrgb4444" value="0x32315258" summary="16-bit xRGB format, [15:0] x:R:G:B 4:4:4:4 little endian"/>
341+ <entry name="xbgr4444" value="0x32314258" summary="16-bit xBGR format, [15:0] x:B:G:R 4:4:4:4 little endian"/>
342+ <entry name="rgbx4444" value="0x32315852" summary="16-bit RGBx format, [15:0] R:G:B:x 4:4:4:4 little endian"/>
343+ <entry name="bgrx4444" value="0x32315842" summary="16-bit BGRx format, [15:0] B:G:R:x 4:4:4:4 little endian"/>
344+ <entry name="argb4444" value="0x32315241" summary="16-bit ARGB format, [15:0] A:R:G:B 4:4:4:4 little endian"/>
345+ <entry name="abgr4444" value="0x32314241" summary="16-bit ABGR format, [15:0] A:B:G:R 4:4:4:4 little endian"/>
346+ <entry name="rgba4444" value="0x32314152" summary="16-bit RGBA format, [15:0] R:G:B:A 4:4:4:4 little endian"/>
347+ <entry name="bgra4444" value="0x32314142" summary="16-bit BGRA format, [15:0] B:G:R:A 4:4:4:4 little endian"/>
348+ <entry name="xrgb1555" value="0x35315258" summary="16-bit xRGB format, [15:0] x:R:G:B 1:5:5:5 little endian"/>
349+ <entry name="xbgr1555" value="0x35314258" summary="16-bit xBGR 1555 format, [15:0] x:B:G:R 1:5:5:5 little endian"/>
350+ <entry name="rgbx5551" value="0x35315852" summary="16-bit RGBx 5551 format, [15:0] R:G:B:x 5:5:5:1 little endian"/>
351+ <entry name="bgrx5551" value="0x35315842" summary="16-bit BGRx 5551 format, [15:0] B:G:R:x 5:5:5:1 little endian"/>
352+ <entry name="argb1555" value="0x35315241" summary="16-bit ARGB 1555 format, [15:0] A:R:G:B 1:5:5:5 little endian"/>
353+ <entry name="abgr1555" value="0x35314241" summary="16-bit ABGR 1555 format, [15:0] A:B:G:R 1:5:5:5 little endian"/>
354+ <entry name="rgba5551" value="0x35314152" summary="16-bit RGBA 5551 format, [15:0] R:G:B:A 5:5:5:1 little endian"/>
355+ <entry name="bgra5551" value="0x35314142" summary="16-bit BGRA 5551 format, [15:0] B:G:R:A 5:5:5:1 little endian"/>
356+ <entry name="rgb565" value="0x36314752" summary="16-bit RGB 565 format, [15:0] R:G:B 5:6:5 little endian"/>
357+ <entry name="bgr565" value="0x36314742" summary="16-bit BGR 565 format, [15:0] B:G:R 5:6:5 little endian"/>
358+ <entry name="rgb888" value="0x34324752" summary="24-bit RGB format, [23:0] R:G:B little endian"/>
359+ <entry name="bgr888" value="0x34324742" summary="24-bit BGR format, [23:0] B:G:R little endian"/>
360+ <entry name="xbgr8888" value="0x34324258" summary="32-bit xBGR format, [31:0] x:B:G:R 8:8:8:8 little endian"/>
361+ <entry name="rgbx8888" value="0x34325852" summary="32-bit RGBx format, [31:0] R:G:B:x 8:8:8:8 little endian"/>
362+ <entry name="bgrx8888" value="0x34325842" summary="32-bit BGRx format, [31:0] B:G:R:x 8:8:8:8 little endian"/>
363+ <entry name="abgr8888" value="0x34324241" summary="32-bit ABGR format, [31:0] A:B:G:R 8:8:8:8 little endian"/>
364+ <entry name="rgba8888" value="0x34324152" summary="32-bit RGBA format, [31:0] R:G:B:A 8:8:8:8 little endian"/>
365+ <entry name="bgra8888" value="0x34324142" summary="32-bit BGRA format, [31:0] B:G:R:A 8:8:8:8 little endian"/>
366+ <entry name="xrgb2101010" value="0x30335258" summary="32-bit xRGB format, [31:0] x:R:G:B 2:10:10:10 little endian"/>
367+ <entry name="xbgr2101010" value="0x30334258" summary="32-bit xBGR format, [31:0] x:B:G:R 2:10:10:10 little endian"/>
368+ <entry name="rgbx1010102" value="0x30335852" summary="32-bit RGBx format, [31:0] R:G:B:x 10:10:10:2 little endian"/>
369+ <entry name="bgrx1010102" value="0x30335842" summary="32-bit BGRx format, [31:0] B:G:R:x 10:10:10:2 little endian"/>
370+ <entry name="argb2101010" value="0x30335241" summary="32-bit ARGB format, [31:0] A:R:G:B 2:10:10:10 little endian"/>
371+ <entry name="abgr2101010" value="0x30334241" summary="32-bit ABGR format, [31:0] A:B:G:R 2:10:10:10 little endian"/>
372+ <entry name="rgba1010102" value="0x30334152" summary="32-bit RGBA format, [31:0] R:G:B:A 10:10:10:2 little endian"/>
373+ <entry name="bgra1010102" value="0x30334142" summary="32-bit BGRA format, [31:0] B:G:R:A 10:10:10:2 little endian"/>
374+ <entry name="yuyv" value="0x56595559" summary="packed YCbCr format, [31:0] Cr0:Y1:Cb0:Y0 8:8:8:8 little endian"/>
375+ <entry name="yvyu" value="0x55595659" summary="packed YCbCr format, [31:0] Cb0:Y1:Cr0:Y0 8:8:8:8 little endian"/>
376+ <entry name="uyvy" value="0x59565955" summary="packed YCbCr format, [31:0] Y1:Cr0:Y0:Cb0 8:8:8:8 little endian"/>
377+ <entry name="vyuy" value="0x59555956" summary="packed YCbCr format, [31:0] Y1:Cb0:Y0:Cr0 8:8:8:8 little endian"/>
378+ <entry name="ayuv" value="0x56555941" summary="packed AYCbCr format, [31:0] A:Y:Cb:Cr 8:8:8:8 little endian"/>
379+ <entry name="nv12" value="0x3231564e" summary="2 plane YCbCr Cr:Cb format, 2x2 subsampled Cr:Cb plane"/>
380+ <entry name="nv21" value="0x3132564e" summary="2 plane YCbCr Cb:Cr format, 2x2 subsampled Cb:Cr plane"/>
381+ <entry name="nv16" value="0x3631564e" summary="2 plane YCbCr Cr:Cb format, 2x1 subsampled Cr:Cb plane"/>
382+ <entry name="nv61" value="0x3136564e" summary="2 plane YCbCr Cb:Cr format, 2x1 subsampled Cb:Cr plane"/>
383+ <entry name="yuv410" value="0x39565559" summary="3 plane YCbCr format, 4x4 subsampled Cb (1) and Cr (2) planes"/>
384+ <entry name="yvu410" value="0x39555659" summary="3 plane YCbCr format, 4x4 subsampled Cr (1) and Cb (2) planes"/>
385+ <entry name="yuv411" value="0x31315559" summary="3 plane YCbCr format, 4x1 subsampled Cb (1) and Cr (2) planes"/>
386+ <entry name="yvu411" value="0x31315659" summary="3 plane YCbCr format, 4x1 subsampled Cr (1) and Cb (2) planes"/>
387+ <entry name="yuv420" value="0x32315559" summary="3 plane YCbCr format, 2x2 subsampled Cb (1) and Cr (2) planes"/>
388+ <entry name="yvu420" value="0x32315659" summary="3 plane YCbCr format, 2x2 subsampled Cr (1) and Cb (2) planes"/>
389+ <entry name="yuv422" value="0x36315559" summary="3 plane YCbCr format, 2x1 subsampled Cb (1) and Cr (2) planes"/>
390+ <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr format, 2x1 subsampled Cr (1) and Cb (2) planes"/>
391+ <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr format, non-subsampled Cb (1) and Cr (2) planes"/>
392+ <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr format, non-subsampled Cr (1) and Cb (2) planes"/>
393+ <entry name="r8" value="0x20203852" summary="[7:0] R"/>
394+ <entry name="r16" value="0x20363152" summary="[15:0] R little endian"/>
395+ <entry name="rg88" value="0x38384752" summary="[15:0] R:G 8:8 little endian"/>
396+ <entry name="gr88" value="0x38385247" summary="[15:0] G:R 8:8 little endian"/>
397+ <entry name="rg1616" value="0x32334752" summary="[31:0] R:G 16:16 little endian"/>
398+ <entry name="gr1616" value="0x32335247" summary="[31:0] G:R 16:16 little endian"/>
399+ <entry name="xrgb16161616f" value="0x48345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
400+ <entry name="xbgr16161616f" value="0x48344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
401+ <entry name="argb16161616f" value="0x48345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
402+ <entry name="abgr16161616f" value="0x48344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
403+ <entry name="xyuv8888" value="0x56555958" summary="[31:0] X:Y:Cb:Cr 8:8:8:8 little endian"/>
404+ <entry name="vuy888" value="0x34325556" summary="[23:0] Cr:Cb:Y 8:8:8 little endian"/>
405+ <entry name="vuy101010" value="0x30335556" summary="Y followed by U then V, 10:10:10. Non-linear modifier only"/>
406+ <entry name="y210" value="0x30313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 10:6:10:6:10:6:10:6 little endian per 2 Y pixels"/>
407+ <entry name="y212" value="0x32313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 12:4:12:4:12:4:12:4 little endian per 2 Y pixels"/>
408+ <entry name="y216" value="0x36313259" summary="[63:0] Cr0:Y1:Cb0:Y0 16:16:16:16 little endian per 2 Y pixels"/>
409+ <entry name="y410" value="0x30313459" summary="[31:0] A:Cr:Y:Cb 2:10:10:10 little endian"/>
410+ <entry name="y412" value="0x32313459" summary="[63:0] A:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
411+ <entry name="y416" value="0x36313459" summary="[63:0] A:Cr:Y:Cb 16:16:16:16 little endian"/>
412+ <entry name="xvyu2101010" value="0x30335658" summary="[31:0] X:Cr:Y:Cb 2:10:10:10 little endian"/>
413+ <entry name="xvyu12_16161616" value="0x36335658" summary="[63:0] X:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
414+ <entry name="xvyu16161616" value="0x38345658" summary="[63:0] X:Cr:Y:Cb 16:16:16:16 little endian"/>
415+ <entry name="y0l0" value="0x304c3059" summary="[63:0] A3:A2:Y3:0:Cr0:0:Y2:0:A1:A0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
416+ <entry name="x0l0" value="0x304c3058" summary="[63:0] X3:X2:Y3:0:Cr0:0:Y2:0:X1:X0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
417+ <entry name="y0l2" value="0x324c3059" summary="[63:0] A3:A2:Y3:Cr0:Y2:A1:A0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
418+ <entry name="x0l2" value="0x324c3058" summary="[63:0] X3:X2:Y3:Cr0:Y2:X1:X0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
419+ <entry name="yuv420_8bit" value="0x38305559"/>
420+ <entry name="yuv420_10bit" value="0x30315559"/>
421+ <entry name="xrgb8888_a8" value="0x38415258"/>
422+ <entry name="xbgr8888_a8" value="0x38414258"/>
423+ <entry name="rgbx8888_a8" value="0x38415852"/>
424+ <entry name="bgrx8888_a8" value="0x38415842"/>
425+ <entry name="rgb888_a8" value="0x38413852"/>
426+ <entry name="bgr888_a8" value="0x38413842"/>
427+ <entry name="rgb565_a8" value="0x38413552"/>
428+ <entry name="bgr565_a8" value="0x38413542"/>
429+ <entry name="nv24" value="0x3432564e" summary="non-subsampled Cr:Cb plane"/>
430+ <entry name="nv42" value="0x3234564e" summary="non-subsampled Cb:Cr plane"/>
431+ <entry name="p210" value="0x30313250" summary="2x1 subsampled Cr:Cb plane, 10 bit per channel"/>
432+ <entry name="p010" value="0x30313050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel"/>
433+ <entry name="p012" value="0x32313050" summary="2x2 subsampled Cr:Cb plane 12 bits per channel"/>
434+ <entry name="p016" value="0x36313050" summary="2x2 subsampled Cr:Cb plane 16 bits per channel"/>
435+ <entry name="axbxgxrx106106106106" value="0x30314241" summary="[63:0] A:x:B:x:G:x:R:x 10:6:10:6:10:6:10:6 little endian"/>
436+ <entry name="nv15" value="0x3531564e" summary="2x2 subsampled Cr:Cb plane"/>
437+ <entry name="q410" value="0x30313451"/>
438+ <entry name="q401" value="0x31303451"/>
439+ <entry name="xrgb16161616" value="0x38345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
440+ <entry name="xbgr16161616" value="0x38344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
441+ <entry name="argb16161616" value="0x38345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
442+ <entry name="abgr16161616" value="0x38344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
443+ <entry name="c1" value="0x20203143" summary="[7:0] C0:C1:C2:C3:C4:C5:C6:C7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
444+ <entry name="c2" value="0x20203243" summary="[7:0] C0:C1:C2:C3 2:2:2:2 four pixels/byte"/>
445+ <entry name="c4" value="0x20203443" summary="[7:0] C0:C1 4:4 two pixels/byte"/>
446+ <entry name="d1" value="0x20203144" summary="[7:0] D0:D1:D2:D3:D4:D5:D6:D7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
447+ <entry name="d2" value="0x20203244" summary="[7:0] D0:D1:D2:D3 2:2:2:2 four pixels/byte"/>
448+ <entry name="d4" value="0x20203444" summary="[7:0] D0:D1 4:4 two pixels/byte"/>
449+ <entry name="d8" value="0x20203844" summary="[7:0] D"/>
450+ <entry name="r1" value="0x20203152" summary="[7:0] R0:R1:R2:R3:R4:R5:R6:R7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
451+ <entry name="r2" value="0x20203252" summary="[7:0] R0:R1:R2:R3 2:2:2:2 four pixels/byte"/>
452+ <entry name="r4" value="0x20203452" summary="[7:0] R0:R1 4:4 two pixels/byte"/>
453+ <entry name="r10" value="0x20303152" summary="[15:0] x:R 6:10 little endian"/>
454+ <entry name="r12" value="0x20323152" summary="[15:0] x:R 4:12 little endian"/>
455+ <entry name="avuy8888" value="0x59555641" summary="[31:0] A:Cr:Cb:Y 8:8:8:8 little endian"/>
456+ <entry name="xvuy8888" value="0x59555658" summary="[31:0] X:Cr:Cb:Y 8:8:8:8 little endian"/>
457+ <entry name="p030" value="0x30333050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel packed"/>
458+ <entry name="rgb161616" value="0x38344752" summary="[47:0] R:G:B 16:16:16 little endian"/>
459+ <entry name="bgr161616" value="0x38344742" summary="[47:0] B:G:R 16:16:16 little endian"/>
460+ <entry name="r16f" value="0x48202052" summary="[15:0] R 16 little endian"/>
461+ <entry name="gr1616f" value="0x48205247" summary="[31:0] G:R 16:16 little endian"/>
462+ <entry name="bgr161616f" value="0x48524742" summary="[47:0] B:G:R 16:16:16 little endian"/>
463+ <entry name="r32f" value="0x46202052" summary="[31:0] R 32 little endian"/>
464+ <entry name="gr3232f" value="0x46205247" summary="[63:0] G:R 32:32 little endian"/>
465+ <entry name="bgr323232f" value="0x46524742" summary="[95:0] B:G:R 32:32:32 little endian"/>
466+ <entry name="abgr32323232f" value="0x46384241" summary="[127:0] A:B:G:R 32:32:32:32 little endian"/>
467+ <entry name="nv20" value="0x3032564e" summary="2x1 subsampled Cr:Cb plane"/>
468+ <entry name="nv30" value="0x3033564e" summary="non-subsampled Cr:Cb plane"/>
469+ <entry name="s010" value="0x30313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
470+ <entry name="s210" value="0x30313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
471+ <entry name="s410" value="0x30313453" summary="non-subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
472+ <entry name="s012" value="0x32313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
473+ <entry name="s212" value="0x32313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
474+ <entry name="s412" value="0x32313453" summary="non-subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
475+ <entry name="s016" value="0x36313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
476+ <entry name="s216" value="0x36313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
477+ <entry name="s416" value="0x36313453" summary="non-subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
478+ <entry name="xvuy2101010" value="0x30335958" summary="[31:0] x:Cr:Cb:Y 2:10:10:10 little endian"/>
479+ <entry name="p230" value="0x30333250" summary="2x1 subsampled Cr:Cb plane 10 bits per channel packed"/>
480+ <entry name="t430" value="0x30333454"/>
481+ <entry name="y8" value="0x59455247" summary="8-bit Y-only"/>
482+ <entry name="xyyy2101010" value="0x34415059" summary="[31:0] x:Y2:Y1:Y0 2:10:10:10 little endian"/>
483+ </enum>
484+
485+ <request name="create_pool">
486+ <description summary="create a shm pool">
487+ Create a new wl_shm_pool object.
488+
489+ The pool can be used to create shared memory based buffer
490+ objects. The server will mmap size bytes of the passed file
491+ descriptor, to use as backing memory for the pool.
492+ </description>
493+ <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
494+ <arg name="fd" type="fd" summary="file descriptor for the pool"/>
495+ <arg name="size" type="int" summary="pool size, in bytes"/>
496+ </request>
497+
498+ <event name="format">
499+ <description summary="pixel format description">
500+ Informs the client about a valid pixel format that
501+ can be used for buffers. Known formats include
502+ argb8888 and xrgb8888.
503+
504+ Extensions to drm_fourcc.h (or the format enum) do not require
505+ increasing the wl_shm version; as a result, clients may receive format
506+ codes which were not in the list at the time the client was made.
507+ </description>
508+ <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
509+ </event>
510+
511+ <!-- Version 2 additions -->
512+
513+ <request name="release" type="destructor" since="2">
514+ <description summary="release the shm object">
515+ Using this request a client can tell the server that it is not going to
516+ use the shm object anymore.
517+
518+ Objects created via this interface remain unaffected.
519+ </description>
520+ </request>
521+ </interface>
522+
523+ <interface name="wl_buffer" version="1" frozen="true">
524+ <description summary="content for a wl_surface">
525+ A buffer provides the content for a wl_surface. Buffers are
526+ created through factory interfaces such as wl_shm, wp_linux_buffer_params
527+ (from the linux-dmabuf protocol extension) or similar. It has a width and
528+ a height and can be attached to a wl_surface, but the mechanism by which a
529+ client provides and updates the contents is defined by the buffer factory
530+ interface.
531+
532+ Color channels are assumed to be electrical rather than optical (in other
533+ words, encoded with a transfer function) unless otherwise specified. If
534+ the buffer uses a format that has an alpha channel, the alpha channel is
535+ assumed to be premultiplied into the electrical color channel values
536+ (after transfer function encoding) unless otherwise specified.
537+
538+ Note, because wl_buffer objects are created from multiple independent
539+ factory interfaces, the wl_buffer interface is frozen at version 1.
540+ </description>
541+
542+ <request name="destroy" type="destructor">
543+ <description summary="destroy a buffer">
544+ Destroy a buffer. If and how you need to release the backing
545+ storage is defined by the buffer factory interface.
546+
547+ For possible side-effects to a surface, see wl_surface.attach.
548+ </description>
549+ </request>
550+
551+ <event name="release">
552+ <description summary="compositor releases buffer">
553+ Sent when this wl_buffer is no longer used by the compositor.
554+
555+ For more information on when release events may or may not be sent,
556+ and what consequences it has, please see the description of
557+ wl_surface.attach.
558+
559+ If a client receives a release event before the frame callback
560+ requested in the same wl_surface.commit that attaches this
561+ wl_buffer to a surface, then the client is immediately free to
562+ reuse the buffer and its backing storage, and does not need a
563+ second buffer for the next surface content update. Typically
564+ this is possible, when the compositor maintains a copy of the
565+ wl_surface contents, e.g. as a GL texture. This is an important
566+ optimization for GL(ES) compositors with wl_shm clients.
567+ </description>
568+ </event>
569+ </interface>
570+
571+ <interface name="wl_data_offer" version="4">
572+ <description summary="offer to transfer data">
573+ A wl_data_offer represents a piece of data offered for transfer
574+ by another client (the source client). It is used by the
575+ copy-and-paste and drag-and-drop mechanisms. The offer
576+ describes the different mime types that the data can be
577+ converted to and provides the mechanism for transferring the
578+ data directly from the source client.
579+ </description>
580+
581+ <enum name="error">
582+ <entry name="invalid_finish" value="0"
583+ summary="finish request was called untimely"/>
584+ <entry name="invalid_action_mask" value="1"
585+ summary="action mask contains invalid values"/>
586+ <entry name="invalid_action" value="2"
587+ summary="action argument has an invalid value"/>
588+ <entry name="invalid_offer" value="3"
589+ summary="offer doesn't accept this request"/>
590+ </enum>
591+
592+ <request name="accept">
593+ <description summary="accept one of the offered mime types">
594+ Indicate that the client can accept the given mime type, or
595+ NULL for not accepted.
596+
597+ For objects of version 2 or older, this request is used by the
598+ client to give feedback whether the client can receive the given
599+ mime type, or NULL if none is accepted; the feedback does not
600+ determine whether the drag-and-drop operation succeeds or not.
601+
602+ For objects of version 3 or newer, this request determines the
603+ final result of the drag-and-drop operation. If the end result
604+ is that no mime types were accepted, the drag-and-drop operation
605+ will be cancelled and the corresponding drag source will receive
606+ wl_data_source.cancelled. Clients may still use this event in
607+ conjunction with wl_data_source.action for feedback.
608+ </description>
609+ <arg name="serial" type="uint" summary="serial number of the accept request"/>
610+ <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the client"/>
611+ </request>
612+
613+ <request name="receive">
614+ <description summary="request that the data is transferred">
615+ To transfer the offered data, the client issues this request
616+ and indicates the mime type it wants to receive. The transfer
617+ happens through the passed file descriptor (typically created
618+ with the pipe system call). The source client writes the data
619+ in the mime type representation requested and then closes the
620+ file descriptor.
621+
622+ The receiving client reads from the read end of the pipe until
623+ EOF and then closes its end, at which point the transfer is
624+ complete.
625+
626+ This request may happen multiple times for different mime types,
627+ both before and after wl_data_device.drop. Drag-and-drop destination
628+ clients may preemptively fetch data or examine it more closely to
629+ determine acceptance.
630+ </description>
631+ <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
632+ <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
633+ </request>
634+
635+ <request name="destroy" type="destructor">
636+ <description summary="destroy data offer">
637+ Destroy the data offer.
638+ </description>
639+ </request>
640+
641+ <event name="offer">
642+ <description summary="advertise offered mime type">
643+ Sent immediately after creating the wl_data_offer object. One
644+ event per offered mime type.
645+ </description>
646+ <arg name="mime_type" type="string" summary="offered mime type"/>
647+ </event>
648+
649+ <!-- Version 3 additions -->
650+
651+ <request name="finish" since="3">
652+ <description summary="the offer will no longer be used">
653+ Notifies the compositor that the drag destination successfully
654+ finished the drag-and-drop operation.
655+
656+ Upon receiving this request, the compositor will emit
657+ wl_data_source.dnd_finished on the drag source client.
658+
659+ It is a client error to perform other requests than
660+ wl_data_offer.destroy after this one. It is also an error to perform
661+ this request after a NULL mime type has been set in
662+ wl_data_offer.accept or no action was received through
663+ wl_data_offer.action.
664+
665+ If wl_data_offer.finish request is received for a non drag and drop
666+ operation, the invalid_finish protocol error is raised.
667+ </description>
668+ </request>
669+
670+ <request name="set_actions" since="3">
671+ <description summary="set the available/preferred drag-and-drop actions">
672+ Sets the actions that the destination side client supports for
673+ this operation. This request may trigger the emission of
674+ wl_data_source.action and wl_data_offer.action events if the compositor
675+ needs to change the selected action.
676+
677+ This request can be called multiple times throughout the
678+ drag-and-drop operation, typically in response to wl_data_device.enter
679+ or wl_data_device.motion events.
680+
681+ This request determines the final result of the drag-and-drop
682+ operation. If the end result is that no action is accepted,
683+ the drag source will receive wl_data_source.cancelled.
684+
685+ The dnd_actions argument must contain only values expressed in the
686+ wl_data_device_manager.dnd_actions enum, and the preferred_action
687+ argument must only contain one of those values set, otherwise it
688+ will result in a protocol error.
689+
690+ While managing an "ask" action, the destination drag-and-drop client
691+ may perform further wl_data_offer.receive requests, and is expected
692+ to perform one last wl_data_offer.set_actions request with a preferred
693+ action other than "ask" (and optionally wl_data_offer.accept) before
694+ requesting wl_data_offer.finish, in order to convey the action selected
695+ by the user. If the preferred action is not in the
696+ wl_data_offer.source_actions mask, an error will be raised.
697+
698+ If the "ask" action is dismissed (e.g. user cancellation), the client
699+ is expected to perform wl_data_offer.destroy right away.
700+
701+ This request can only be made on drag-and-drop offers, a protocol error
702+ will be raised otherwise.
703+ </description>
704+ <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
705+ enum="wl_data_device_manager.dnd_action"/>
706+ <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
707+ enum="wl_data_device_manager.dnd_action"/>
708+ </request>
709+
710+ <event name="source_actions" since="3">
711+ <description summary="notify the source-side available actions">
712+ This event indicates the actions offered by the data source. It
713+ will be sent immediately after creating the wl_data_offer object,
714+ or anytime the source side changes its offered actions through
715+ wl_data_source.set_actions.
716+ </description>
717+ <arg name="source_actions" type="uint" summary="actions offered by the data source"
718+ enum="wl_data_device_manager.dnd_action"/>
719+ </event>
720+
721+ <event name="action" since="3">
722+ <description summary="notify the selected action">
723+ This event indicates the action selected by the compositor after
724+ matching the source/destination side actions. Only one action (or
725+ none) will be offered here.
726+
727+ This event can be emitted multiple times during the drag-and-drop
728+ operation in response to destination side action changes through
729+ wl_data_offer.set_actions.
730+
731+ This event will no longer be emitted after wl_data_device.drop
732+ happened on the drag-and-drop destination, the client must
733+ honor the last action received, or the last preferred one set
734+ through wl_data_offer.set_actions when handling an "ask" action.
735+
736+ Compositors may also change the selected action on the fly, mainly
737+ in response to keyboard modifier changes during the drag-and-drop
738+ operation.
739+
740+ The most recent action received is always the valid one. Prior to
741+ receiving wl_data_device.drop, the chosen action may change (e.g.
742+ due to keyboard modifiers being pressed). At the time of receiving
743+ wl_data_device.drop the drag-and-drop destination must honor the
744+ last action received.
745+
746+ Action changes may still happen after wl_data_device.drop,
747+ especially on "ask" actions, where the drag-and-drop destination
748+ may choose another action afterwards. Action changes happening
749+ at this stage are always the result of inter-client negotiation, the
750+ compositor shall no longer be able to induce a different action.
751+
752+ Upon "ask" actions, it is expected that the drag-and-drop destination
753+ may potentially choose a different action and/or mime type,
754+ based on wl_data_offer.source_actions and finally chosen by the
755+ user (e.g. popping up a menu with the available options). The
756+ final wl_data_offer.set_actions and wl_data_offer.accept requests
757+ must happen before the call to wl_data_offer.finish.
758+ </description>
759+ <arg name="dnd_action" type="uint" summary="action selected by the compositor"
760+ enum="wl_data_device_manager.dnd_action"/>
761+ </event>
762+ </interface>
763+
764+ <interface name="wl_data_source" version="4">
765+ <description summary="offer to transfer data">
766+ The wl_data_source object is the source side of a wl_data_offer.
767+ It is created by the source client in a data transfer and
768+ provides a way to describe the offered data and a way to respond
769+ to requests to transfer the data.
770+ </description>
771+
772+ <enum name="error">
773+ <entry name="invalid_action_mask" value="0"
774+ summary="action mask contains invalid values"/>
775+ <entry name="invalid_source" value="1"
776+ summary="source doesn't accept this request"/>
777+ </enum>
778+
779+ <request name="offer">
780+ <description summary="add an offered mime type">
781+ This request adds a mime type to the set of mime types
782+ advertised to targets. Can be called several times to offer
783+ multiple types.
784+ </description>
785+ <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
786+ </request>
787+
788+ <request name="destroy" type="destructor">
789+ <description summary="destroy the data source">
790+ Destroy the data source.
791+ </description>
792+ </request>
793+
794+ <event name="target">
795+ <description summary="a target accepts an offered mime type">
796+ Sent when a target accepts pointer_focus or motion events. If
797+ a target does not accept any of the offered types, type is NULL.
798+
799+ Used for feedback during drag-and-drop.
800+ </description>
801+ <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
802+ </event>
803+
804+ <event name="send">
805+ <description summary="send the data">
806+ Request for data from the client. Send the data as the
807+ specified mime type over the passed file descriptor, then
808+ close it.
809+ </description>
810+ <arg name="mime_type" type="string" summary="mime type for the data"/>
811+ <arg name="fd" type="fd" summary="file descriptor for the data"/>
812+ </event>
813+
814+ <event name="cancelled">
815+ <description summary="selection was cancelled">
816+ This data source is no longer valid. There are several reasons why
817+ this could happen:
818+
819+ - The data source has been replaced by another data source.
820+ - The drag-and-drop operation was performed, but the drop destination
821+ did not accept any of the mime types offered through
822+ wl_data_source.target.
823+ - The drag-and-drop operation was performed, but the drop destination
824+ did not select any of the actions present in the mask offered through
825+ wl_data_source.action.
826+ - The drag-and-drop operation was performed but didn't happen over a
827+ surface.
828+ - The compositor cancelled the drag-and-drop operation (e.g. compositor
829+ dependent timeouts to avoid stale drag-and-drop transfers).
830+
831+ The client should clean up and destroy this data source.
832+
833+ For objects of version 2 or older, wl_data_source.cancelled will
834+ only be emitted if the data source was replaced by another data
835+ source.
836+ </description>
837+ </event>
838+
839+ <!-- Version 3 additions -->
840+
841+ <request name="set_actions" since="3">
842+ <description summary="set the available drag-and-drop actions">
843+ Sets the actions that the source side client supports for this
844+ operation. This request may trigger wl_data_source.action and
845+ wl_data_offer.action events if the compositor needs to change the
846+ selected action.
847+
848+ The dnd_actions argument must contain only values expressed in the
849+ wl_data_device_manager.dnd_actions enum, otherwise it will result
850+ in a protocol error.
851+
852+ This request must be made once only, and can only be made on sources
853+ used in drag-and-drop, so it must be performed before
854+ wl_data_device.start_drag. Attempting to use the source other than
855+ for drag-and-drop will raise a protocol error.
856+ </description>
857+ <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
858+ enum="wl_data_device_manager.dnd_action"/>
859+ </request>
860+
861+ <event name="dnd_drop_performed" since="3">
862+ <description summary="the drag-and-drop operation physically finished">
863+ The user performed the drop action. This event does not indicate
864+ acceptance, wl_data_source.cancelled may still be emitted afterwards
865+ if the drop destination does not accept any mime type.
866+
867+ However, this event might not be received if the compositor cancelled
868+ the drag-and-drop operation before this event could happen.
869+
870+ Note that the data_source may still be used in the future and should
871+ not be destroyed here.
872+ </description>
873+ </event>
874+
875+ <event name="dnd_finished" since="3">
876+ <description summary="the drag-and-drop operation concluded">
877+ The drop destination finished interoperating with this data
878+ source, so the client is now free to destroy this data source and
879+ free all associated data.
880+
881+ If the action used to perform the operation was "move", the
882+ source can now delete the transferred data.
883+ </description>
884+ </event>
885+
886+ <event name="action" since="3">
887+ <description summary="notify the selected action">
888+ This event indicates the action selected by the compositor after
889+ matching the source/destination side actions. Only one action (or
890+ none) will be offered here.
891+
892+ This event can be emitted multiple times during the drag-and-drop
893+ operation, mainly in response to destination side changes through
894+ wl_data_offer.set_actions, and as the data device enters/leaves
895+ surfaces.
896+
897+ It is only possible to receive this event after
898+ wl_data_source.dnd_drop_performed if the drag-and-drop operation
899+ ended in an "ask" action, in which case the final wl_data_source.action
900+ event will happen immediately before wl_data_source.dnd_finished.
901+
902+ Compositors may also change the selected action on the fly, mainly
903+ in response to keyboard modifier changes during the drag-and-drop
904+ operation.
905+
906+ The most recent action received is always the valid one. The chosen
907+ action may change alongside negotiation (e.g. an "ask" action can turn
908+ into a "move" operation), so the effects of the final action must
909+ always be applied in wl_data_source.dnd_finished.
910+
911+ Clients can trigger cursor surface changes from this point, so
912+ they reflect the current action.
913+ </description>
914+ <arg name="dnd_action" type="uint" summary="action selected by the compositor"
915+ enum="wl_data_device_manager.dnd_action"/>
916+ </event>
917+ </interface>
918+
919+ <interface name="wl_data_device" version="4">
920+ <description summary="data transfer device">
921+ There is one wl_data_device per seat which can be obtained
922+ from the global wl_data_device_manager singleton.
923+
924+ A wl_data_device provides access to inter-client data transfer
925+ mechanisms such as copy-and-paste and drag-and-drop.
926+ </description>
927+
928+ <enum name="error">
929+ <entry name="role" value="0" summary="given wl_surface has another role"/>
930+ <entry name="used_source" value="1" summary="source has already been used"/>
931+ </enum>
932+
933+ <request name="start_drag">
934+ <description summary="start drag-and-drop operation">
935+ This request asks the compositor to start a drag-and-drop
936+ operation on behalf of the client.
937+
938+ The source argument is the data source that provides the data
939+ for the eventual data transfer. If source is NULL, enter, leave
940+ and motion events are sent only to the client that initiated the
941+ drag and the client is expected to handle the data passing
942+ internally. If source is destroyed, the drag-and-drop session will be
943+ cancelled.
944+
945+ The origin surface is the surface where the drag originates and
946+ the client must have an active implicit grab that matches the
947+ serial.
948+
949+ The icon surface is an optional (can be NULL) surface that
950+ provides an icon to be moved around with the cursor. Initially,
951+ the top-left corner of the icon surface is placed at the cursor
952+ hotspot, but subsequent wl_surface.offset requests can move the
953+ relative position. Attach requests must be confirmed with
954+ wl_surface.commit as usual. The icon surface is given the role of
955+ a drag-and-drop icon. If the icon surface already has another role,
956+ it raises a protocol error.
957+
958+ The input region is ignored for wl_surfaces with the role of a
959+ drag-and-drop icon.
960+
961+ The given source may not be used in any further set_selection or
962+ start_drag requests. Attempting to reuse a previously-used source
963+ may send a used_source error.
964+ </description>
965+ <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
966+ <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
967+ <arg name="icon" type="object" interface="wl_surface" allow-null="true" summary="drag-and-drop icon surface"/>
968+ <arg name="serial" type="uint" summary="serial number of the implicit grab on the origin"/>
969+ </request>
970+
971+ <request name="set_selection">
972+ <description summary="copy data to the selection">
973+ This request asks the compositor to set the selection
974+ to the data from the source on behalf of the client.
975+
976+ To unset the selection, set the source to NULL.
977+
978+ The given source may not be used in any further set_selection or
979+ start_drag requests. Attempting to reuse a previously-used source
980+ may send a used_source error.
981+ </description>
982+ <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
983+ <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
984+ </request>
985+
986+ <event name="data_offer">
987+ <description summary="introduce a new wl_data_offer">
988+ The data_offer event introduces a new wl_data_offer object,
989+ which will subsequently be used in either the
990+ data_device.enter event (for drag-and-drop) or the
991+ data_device.selection event (for selections). Immediately
992+ following the data_device.data_offer event, the new data_offer
993+ object will send out data_offer.offer events to describe the
994+ mime types it offers.
995+ </description>
996+ <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
997+ </event>
998+
999+ <event name="enter">
1000+ <description summary="initiate drag-and-drop session">
1001+ This event is sent when an active drag-and-drop pointer enters
1002+ a surface owned by the client. The position of the pointer at
1003+ enter time is provided by the x and y arguments, in surface-local
1004+ coordinates.
1005+ </description>
1006+ <arg name="serial" type="uint" summary="serial number of the enter event"/>
1007+ <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
1008+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
1009+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
1010+ <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
1011+ summary="source data_offer object"/>
1012+ </event>
1013+
1014+ <event name="leave">
1015+ <description summary="end drag-and-drop session">
1016+ This event is sent when the drag-and-drop pointer leaves the
1017+ surface and the session ends. The client must destroy the
1018+ wl_data_offer introduced at enter time at this point.
1019+ </description>
1020+ </event>
1021+
1022+ <event name="motion">
1023+ <description summary="drag-and-drop session motion">
1024+ This event is sent when the drag-and-drop pointer moves within
1025+ the currently focused surface. The new position of the pointer
1026+ is provided by the x and y arguments, in surface-local
1027+ coordinates.
1028+ </description>
1029+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
1030+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
1031+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
1032+ </event>
1033+
1034+ <event name="drop">
1035+ <description summary="end drag-and-drop session successfully">
1036+ The event is sent when a drag-and-drop operation is ended
1037+ because the implicit grab is removed.
1038+
1039+ The drag-and-drop destination is expected to honor the last action
1040+ received through wl_data_offer.action, if the resulting action is
1041+ "copy" or "move", the destination can still perform
1042+ wl_data_offer.receive requests, and is expected to end all
1043+ transfers with a wl_data_offer.finish request.
1044+
1045+ If the resulting action is "ask", the action will not be considered
1046+ final. The drag-and-drop destination is expected to perform one last
1047+ wl_data_offer.set_actions request, or wl_data_offer.destroy in order
1048+ to cancel the operation.
1049+ </description>
1050+ </event>
1051+
1052+ <event name="selection">
1053+ <description summary="advertise new selection">
1054+ The selection event is sent out to notify the client of a new
1055+ wl_data_offer for the selection for this device. The
1056+ data_device.data_offer and the data_offer.offer events are
1057+ sent out immediately before this event to introduce the data
1058+ offer object. The selection event is sent to a client
1059+ immediately before receiving keyboard focus and when a new
1060+ selection is set while the client has keyboard focus. The
1061+ data_offer is valid until a new data_offer or NULL is received
1062+ or until the client loses keyboard focus. Switching surface with
1063+ keyboard focus within the same client doesn't mean a new selection
1064+ will be sent. The client must destroy the previous selection
1065+ data_offer, if any, upon receiving this event.
1066+ </description>
1067+ <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
1068+ summary="selection data_offer object"/>
1069+ </event>
1070+
1071+ <!-- Version 2 additions -->
1072+
1073+ <request name="release" type="destructor" since="2">
1074+ <description summary="destroy data device">
1075+ This request destroys the data device.
1076+ </description>
1077+ </request>
1078+ </interface>
1079+
1080+ <interface name="wl_data_device_manager" version="4">
1081+ <description summary="data transfer interface">
1082+ The wl_data_device_manager is a singleton global object that
1083+ provides access to inter-client data transfer mechanisms such as
1084+ copy-and-paste and drag-and-drop. These mechanisms are tied to
1085+ a wl_seat and this interface lets a client get a wl_data_device
1086+ corresponding to a wl_seat.
1087+
1088+ Depending on the version bound, the objects created from the bound
1089+ wl_data_device_manager object will have different requirements for
1090+ functioning properly. See wl_data_source.set_actions,
1091+ wl_data_offer.accept and wl_data_offer.finish for details.
1092+ </description>
1093+
1094+ <request name="create_data_source">
1095+ <description summary="create a new data source">
1096+ Create a new data source.
1097+ </description>
1098+ <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
1099+ </request>
1100+
1101+ <request name="get_data_device">
1102+ <description summary="create a new data device">
1103+ Create a new data device for a given seat.
1104+ </description>
1105+ <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
1106+ <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
1107+ </request>
1108+
1109+ <!-- Version 3 additions -->
1110+
1111+ <enum name="dnd_action" bitfield="true" since="3">
1112+ <description summary="drag and drop actions">
1113+ This is a bitmask of the available/preferred actions in a
1114+ drag-and-drop operation.
1115+
1116+ In the compositor, the selected action is a result of matching the
1117+ actions offered by the source and destination sides. "action" events
1118+ with a "none" action will be sent to both source and destination if
1119+ there is no match. All further checks will effectively happen on
1120+ (source actions ∩ destination actions).
1121+
1122+ In addition, compositors may also pick different actions in
1123+ reaction to key modifiers being pressed. One common design that
1124+ is used in major toolkits (and the behavior recommended for
1125+ compositors) is:
1126+
1127+ - If no modifiers are pressed, the first match (in bit order)
1128+ will be used.
1129+ - Pressing Shift selects "move", if enabled in the mask.
1130+ - Pressing Control selects "copy", if enabled in the mask.
1131+
1132+ Behavior beyond that is considered implementation-dependent.
1133+ Compositors may for example bind other modifiers (like Alt/Meta)
1134+ or drags initiated with other buttons than BTN_LEFT to specific
1135+ actions (e.g. "ask").
1136+ </description>
1137+ <entry name="none" value="0" summary="no action"/>
1138+ <entry name="copy" value="1" summary="copy action"/>
1139+ <entry name="move" value="2" summary="move action"/>
1140+ <entry name="ask" value="4" summary="ask action"/>
1141+ </enum>
1142+
1143+ <!-- Version 4 additions -->
1144+
1145+ <request name="release" type="destructor" since="4">
1146+ <description summary="destroy wl_data_device_manager">
1147+ This request destroys the wl_data_device_manager. This has no effect on any other
1148+ objects.
1149+ </description>
1150+ </request>
1151+ </interface>
1152+
1153+ <interface name="wl_shell" version="1">
1154+ <description summary="create desktop-style surfaces">
1155+ This interface is implemented by servers that provide
1156+ desktop-style user interfaces.
1157+
1158+ It allows clients to associate a wl_shell_surface with
1159+ a basic surface.
1160+
1161+ Note! This protocol is deprecated and not intended for production use.
1162+ For desktop-style user interfaces, use xdg_shell. Compositors and clients
1163+ should not implement this interface.
1164+ </description>
1165+
1166+ <enum name="error">
1167+ <entry name="role" value="0" summary="given wl_surface has another role"/>
1168+ </enum>
1169+
1170+ <request name="get_shell_surface">
1171+ <description summary="create a shell surface from a surface">
1172+ Create a shell surface for an existing surface. This gives
1173+ the wl_surface the role of a shell surface. If the wl_surface
1174+ already has another role, it raises a protocol error.
1175+
1176+ Only one shell surface can be associated with a given surface.
1177+ </description>
1178+ <arg name="id" type="new_id" interface="wl_shell_surface" summary="shell surface to create"/>
1179+ <arg name="surface" type="object" interface="wl_surface" summary="surface to be given the shell surface role"/>
1180+ </request>
1181+ </interface>
1182+
1183+ <interface name="wl_shell_surface" version="1">
1184+ <description summary="desktop-style metadata interface">
1185+ An interface that may be implemented by a wl_surface, for
1186+ implementations that provide a desktop-style user interface.
1187+
1188+ It provides requests to treat surfaces like toplevel, fullscreen
1189+ or popup windows, move, resize or maximize them, associate
1190+ metadata like title and class, etc.
1191+
1192+ On the server side the object is automatically destroyed when
1193+ the related wl_surface is destroyed. On the client side,
1194+ wl_shell_surface_destroy() must be called before destroying
1195+ the wl_surface object.
1196+ </description>
1197+
1198+ <request name="pong">
1199+ <description summary="respond to a ping event">
1200+ A client must respond to a ping event with a pong request or
1201+ the client may be deemed unresponsive.
1202+ </description>
1203+ <arg name="serial" type="uint" summary="serial number of the ping event"/>
1204+ </request>
1205+
1206+ <request name="move">
1207+ <description summary="start an interactive move">
1208+ Start a pointer-driven move of the surface.
1209+
1210+ This request must be used in response to a button press event.
1211+ The server may ignore move requests depending on the state of
1212+ the surface (e.g. fullscreen or maximized).
1213+ </description>
1214+ <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1215+ <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1216+ </request>
1217+
1218+ <enum name="resize" bitfield="true">
1219+ <description summary="edge values for resizing">
1220+ These values are used to indicate which edge of a surface
1221+ is being dragged in a resize operation. The server may
1222+ use this information to adapt its behavior, e.g. choose
1223+ an appropriate cursor image.
1224+ </description>
1225+ <entry name="none" value="0" summary="no edge"/>
1226+ <entry name="top" value="1" summary="top edge"/>
1227+ <entry name="bottom" value="2" summary="bottom edge"/>
1228+ <entry name="left" value="4" summary="left edge"/>
1229+ <entry name="top_left" value="5" summary="top and left edges"/>
1230+ <entry name="bottom_left" value="6" summary="bottom and left edges"/>
1231+ <entry name="right" value="8" summary="right edge"/>
1232+ <entry name="top_right" value="9" summary="top and right edges"/>
1233+ <entry name="bottom_right" value="10" summary="bottom and right edges"/>
1234+ </enum>
1235+
1236+ <request name="resize">
1237+ <description summary="start an interactive resize">
1238+ Start a pointer-driven resizing of the surface.
1239+
1240+ This request must be used in response to a button press event.
1241+ The server may ignore resize requests depending on the state of
1242+ the surface (e.g. fullscreen or maximized).
1243+ </description>
1244+ <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1245+ <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1246+ <arg name="edges" type="uint" enum="resize" summary="which edge or corner is being dragged"/>
1247+ </request>
1248+
1249+ <request name="set_toplevel">
1250+ <description summary="make the surface a toplevel surface">
1251+ Map the surface as a toplevel surface.
1252+
1253+ A toplevel surface is not fullscreen, maximized or transient.
1254+ </description>
1255+ </request>
1256+
1257+ <enum name="transient" bitfield="true">
1258+ <description summary="details of transient behaviour">
1259+ These flags specify details of the expected behaviour
1260+ of transient surfaces. Used in the set_transient request.
1261+ </description>
1262+ <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
1263+ </enum>
1264+
1265+ <request name="set_transient">
1266+ <description summary="make the surface a transient surface">
1267+ Map the surface relative to an existing surface.
1268+
1269+ The x and y arguments specify the location of the upper left
1270+ corner of the surface relative to the upper left corner of the
1271+ parent surface, in surface-local coordinates.
1272+
1273+ The flags argument controls details of the transient behaviour.
1274+ </description>
1275+ <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1276+ <arg name="x" type="int" summary="surface-local x coordinate"/>
1277+ <arg name="y" type="int" summary="surface-local y coordinate"/>
1278+ <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1279+ </request>
1280+
1281+ <enum name="fullscreen_method">
1282+ <description summary="different method to set the surface fullscreen">
1283+ Hints to indicate to the compositor how to deal with a conflict
1284+ between the dimensions of the surface and the dimensions of the
1285+ output. The compositor is free to ignore this parameter.
1286+ </description>
1287+ <entry name="default" value="0" summary="no preference, apply default policy"/>
1288+ <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
1289+ <entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/>
1290+ <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1291+ </enum>
1292+
1293+ <request name="set_fullscreen">
1294+ <description summary="make the surface a fullscreen surface">
1295+ Map the surface as a fullscreen surface.
1296+
1297+ If an output parameter is given then the surface will be made
1298+ fullscreen on that output. If the client does not specify the
1299+ output then the compositor will apply its policy - usually
1300+ choosing the output on which the surface has the biggest surface
1301+ area.
1302+
1303+ The client may specify a method to resolve a size conflict
1304+ between the output size and the surface size - this is provided
1305+ through the method parameter.
1306+
1307+ The framerate parameter is used only when the method is set
1308+ to "driver", to indicate the preferred framerate. A value of 0
1309+ indicates that the client does not care about framerate. The
1310+ framerate is specified in mHz, that is framerate of 60000 is 60Hz.
1311+
1312+ A method of "scale" or "driver" implies a scaling operation of
1313+ the surface, either via a direct scaling operation or a change of
1314+ the output mode. This will override any kind of output scaling, so
1315+ that mapping a surface with a buffer size equal to the mode can
1316+ fill the screen independent of buffer_scale.
1317+
1318+ A method of "fill" means we don't scale up the buffer, however
1319+ any output scale is applied. This means that you may run into
1320+ an edge case where the application maps a buffer with the same
1321+ size of the output mode but buffer_scale 1 (thus making a
1322+ surface larger than the output). In this case it is allowed to
1323+ downscale the results to fit the screen.
1324+
1325+ The compositor must reply to this request with a configure event
1326+ with the dimensions for the output on which the surface will
1327+ be made fullscreen.
1328+ </description>
1329+ <arg name="method" type="uint" enum="fullscreen_method" summary="method for resolving size conflict"/>
1330+ <arg name="framerate" type="uint" summary="framerate in mHz"/>
1331+ <arg name="output" type="object" interface="wl_output" allow-null="true"
1332+ summary="output on which the surface is to be fullscreen"/>
1333+ </request>
1334+
1335+ <request name="set_popup">
1336+ <description summary="make the surface a popup surface">
1337+ Map the surface as a popup.
1338+
1339+ A popup surface is a transient surface with an added pointer
1340+ grab.
1341+
1342+ An existing implicit grab will be changed to owner-events mode,
1343+ and the popup grab will continue after the implicit grab ends
1344+ (i.e. releasing the mouse button does not cause the popup to
1345+ be unmapped).
1346+
1347+ The popup grab continues until the window is destroyed or a
1348+ mouse button is pressed in any other client's window. A click
1349+ in any of the client's surfaces is reported as normal, however,
1350+ clicks in other clients' surfaces will be discarded and trigger
1351+ the callback.
1352+
1353+ The x and y arguments specify the location of the upper left
1354+ corner of the surface relative to the upper left corner of the
1355+ parent surface, in surface-local coordinates.
1356+ </description>
1357+ <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1358+ <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1359+ <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1360+ <arg name="x" type="int" summary="surface-local x coordinate"/>
1361+ <arg name="y" type="int" summary="surface-local y coordinate"/>
1362+ <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1363+ </request>
1364+
1365+ <request name="set_maximized">
1366+ <description summary="make the surface a maximized surface">
1367+ Map the surface as a maximized surface.
1368+
1369+ If an output parameter is given then the surface will be
1370+ maximized on that output. If the client does not specify the
1371+ output then the compositor will apply its policy - usually
1372+ choosing the output on which the surface has the biggest surface
1373+ area.
1374+
1375+ The compositor will reply with a configure event telling
1376+ the expected new surface size. The operation is completed
1377+ on the next buffer attach to this surface.
1378+
1379+ A maximized surface typically fills the entire output it is
1380+ bound to, except for desktop elements such as panels. This is
1381+ the main difference between a maximized shell surface and a
1382+ fullscreen shell surface.
1383+
1384+ The details depend on the compositor implementation.
1385+ </description>
1386+ <arg name="output" type="object" interface="wl_output" allow-null="true"
1387+ summary="output on which the surface is to be maximized"/>
1388+ </request>
1389+
1390+ <request name="set_title">
1391+ <description summary="set surface title">
1392+ Set a short title for the surface.
1393+
1394+ This string may be used to identify the surface in a task bar,
1395+ window list, or other user interface elements provided by the
1396+ compositor.
1397+
1398+ The string must be encoded in UTF-8.
1399+ </description>
1400+ <arg name="title" type="string" summary="surface title"/>
1401+ </request>
1402+
1403+ <request name="set_class">
1404+ <description summary="set surface class">
1405+ Set a class for the surface.
1406+
1407+ The surface class identifies the general class of applications
1408+ to which the surface belongs. A common convention is to use the
1409+ file name (or the full path if it is a non-standard location) of
1410+ the application's .desktop file as the class.
1411+ </description>
1412+ <arg name="class_" type="string" summary="surface class"/>
1413+ </request>
1414+
1415+ <event name="ping">
1416+ <description summary="ping client">
1417+ Ping a client to check if it is receiving events and sending
1418+ requests. A client is expected to reply with a pong request.
1419+ </description>
1420+ <arg name="serial" type="uint" summary="serial number of the ping"/>
1421+ </event>
1422+
1423+ <event name="configure">
1424+ <description summary="suggest resize">
1425+ The configure event asks the client to resize its surface.
1426+
1427+ The size is a hint, in the sense that the client is free to
1428+ ignore it if it doesn't resize, pick a smaller size (to
1429+ satisfy aspect ratio or resize in steps of NxM pixels).
1430+
1431+ The edges parameter provides a hint about how the surface
1432+ was resized. The client may use this information to decide
1433+ how to adjust its content to the new size (e.g. a scrolling
1434+ area might adjust its content position to leave the viewable
1435+ content unmoved).
1436+
1437+ The client is free to dismiss all but the last configure
1438+ event it received.
1439+
1440+ The width and height arguments specify the size of the window
1441+ in surface-local coordinates.
1442+ </description>
1443+ <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
1444+ <arg name="width" type="int" summary="new width of the surface"/>
1445+ <arg name="height" type="int" summary="new height of the surface"/>
1446+ </event>
1447+
1448+ <event name="popup_done">
1449+ <description summary="popup interaction is done">
1450+ The popup_done event is sent out when a popup grab is broken,
1451+ that is, when the user clicks a surface that doesn't belong
1452+ to the client owning the popup surface.
1453+ </description>
1454+ </event>
1455+ </interface>
1456+
1457+ <interface name="wl_surface" version="7">
1458+ <description summary="an onscreen surface">
1459+ A surface is a rectangular area that may be displayed on zero
1460+ or more outputs, and shown any number of times at the compositor's
1461+ discretion. They can present wl_buffers, receive user input, and
1462+ define a local coordinate system.
1463+
1464+ The size of a surface (and relative positions on it) is described
1465+ in surface-local coordinates, which may differ from the buffer
1466+ coordinates of the pixel content, in case a buffer_transform
1467+ or a buffer_scale is used.
1468+
1469+ A surface without a "role" is fairly useless: a compositor does
1470+ not know where, when or how to present it. The role is the
1471+ purpose of a wl_surface. Examples of roles are a cursor for a
1472+ pointer (as set by wl_pointer.set_cursor), a drag icon
1473+ (wl_data_device.start_drag), a sub-surface
1474+ (wl_subcompositor.get_subsurface), and a window as defined by a
1475+ shell protocol (e.g. wl_shell.get_shell_surface).
1476+
1477+ A surface can have only one role at a time. Initially a
1478+ wl_surface does not have a role. Once a wl_surface is given a
1479+ role, it is set permanently for the whole lifetime of the
1480+ wl_surface object. Giving the current role again is allowed,
1481+ unless explicitly forbidden by the relevant interface
1482+ specification.
1483+
1484+ Surface roles are given by requests in other interfaces such as
1485+ wl_pointer.set_cursor. The request should explicitly mention
1486+ that this request gives a role to a wl_surface. Often, this
1487+ request also creates a new protocol object that represents the
1488+ role and adds additional functionality to wl_surface. When a
1489+ client wants to destroy a wl_surface, they must destroy this role
1490+ object before the wl_surface, otherwise a defunct_role_object error is
1491+ sent.
1492+
1493+ Destroying the role object does not remove the role from the
1494+ wl_surface, but it may stop the wl_surface from "playing the role".
1495+ For instance, if a wl_subsurface object is destroyed, the wl_surface
1496+ it was created for will be unmapped and forget its position and
1497+ z-order. It is allowed to create a wl_subsurface for the same
1498+ wl_surface again, but it is not allowed to use the wl_surface as
1499+ a cursor (cursor is a different role than sub-surface, and role
1500+ switching is not allowed).
1501+ </description>
1502+
1503+ <enum name="error">
1504+ <description summary="wl_surface error values">
1505+ These errors can be emitted in response to wl_surface requests.
1506+ </description>
1507+ <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
1508+ <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
1509+ <entry name="invalid_size" value="2" summary="buffer size is invalid"/>
1510+ <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
1511+ <entry name="defunct_role_object" value="4"
1512+ summary="surface was destroyed before its role object"/>
1513+ <entry name="no_buffer" value="5" summary="no buffer was attached"/>
1514+ </enum>
1515+
1516+ <request name="destroy" type="destructor">
1517+ <description summary="delete surface">
1518+ Deletes the surface and invalidates its object ID.
1519+ </description>
1520+ </request>
1521+
1522+ <request name="attach">
1523+ <description summary="set the surface contents">
1524+ Set a buffer as the content of this surface.
1525+
1526+ The new size of the surface is calculated based on the buffer
1527+ size transformed by the inverse buffer_transform and the
1528+ inverse buffer_scale. This means that at commit time the supplied
1529+ buffer size must be an integer multiple of the buffer_scale. If
1530+ that's not the case, an invalid_size error is sent.
1531+
1532+ The x and y arguments specify the location of the new pending
1533+ buffer's upper left corner, relative to the current buffer's upper
1534+ left corner, in surface-local coordinates. In other words, the
1535+ x and y, combined with the new surface size define in which
1536+ directions the surface's size changes. Setting anything other than 0
1537+ as x and y arguments is discouraged, and should instead be replaced
1538+ with using the separate wl_surface.offset request.
1539+
1540+ When the bound wl_surface version is 5 or higher, passing any
1541+ non-zero x or y is a protocol violation, and will result in an
1542+ 'invalid_offset' error being raised. The x and y arguments are ignored
1543+ and do not change the pending state. To achieve equivalent semantics,
1544+ use wl_surface.offset.
1545+
1546+ Surface contents are double-buffered state, see wl_surface.commit.
1547+
1548+ The initial surface contents are void; there is no content.
1549+ wl_surface.attach assigns the given wl_buffer as the pending
1550+ wl_buffer. wl_surface.commit makes the pending wl_buffer the new
1551+ surface contents, and the size of the surface becomes the size
1552+ calculated from the wl_buffer, as described above. After commit,
1553+ there is no pending buffer until the next attach.
1554+
1555+ Committing a pending wl_buffer allows the compositor to read the
1556+ pixels in the wl_buffer. The compositor may access the pixels at
1557+ any time after the wl_surface.commit request. When the compositor
1558+ will not access the pixels anymore, it will send the
1559+ wl_buffer.release event. Only after receiving wl_buffer.release,
1560+ the client may reuse the wl_buffer. A wl_buffer that has been
1561+ attached and then replaced by another attach instead of committed
1562+ will not receive a release event, and is not used by the
1563+ compositor.
1564+
1565+ If a pending wl_buffer has been committed to more than one wl_surface,
1566+ the delivery of wl_buffer.release events becomes undefined. A well
1567+ behaved client should not rely on wl_buffer.release events in this
1568+ case. Instead, clients hitting this case should use
1569+ wl_surface.get_release or use a protocol extension providing per-commit
1570+ release notifications (if none of these options are available, a
1571+ fallback can be implemented by creating multiple wl_buffer objects from
1572+ the same backing storage).
1573+
1574+ Destroying the wl_buffer after wl_buffer.release does not change
1575+ the surface contents. Destroying the wl_buffer before wl_buffer.release
1576+ is allowed as long as the underlying buffer storage isn't re-used (this
1577+ can happen e.g. on client process termination). However, if the client
1578+ destroys the wl_buffer before receiving the wl_buffer.release event and
1579+ mutates the underlying buffer storage, the surface contents become
1580+ undefined immediately.
1581+
1582+ If wl_surface.attach is sent with a NULL wl_buffer, the
1583+ following wl_surface.commit will remove the surface content.
1584+
1585+ If a pending wl_buffer has been destroyed, the result is not specified.
1586+ Many compositors are known to remove the surface content on the following
1587+ wl_surface.commit, but this behaviour is not universal. Clients seeking to
1588+ maximise compatibility should not destroy pending buffers and should
1589+ ensure that they explicitly remove content from surfaces, even after
1590+ destroying buffers.
1591+ </description>
1592+ <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
1593+ summary="buffer of surface contents"/>
1594+ <arg name="x" type="int" summary="surface-local x coordinate"/>
1595+ <arg name="y" type="int" summary="surface-local y coordinate"/>
1596+ </request>
1597+
1598+ <request name="damage">
1599+ <description summary="mark part of the surface damaged">
1600+ This request is used to describe the regions where the pending
1601+ buffer is different from the current surface contents, and where
1602+ the surface therefore needs to be repainted. The compositor
1603+ ignores the parts of the damage that fall outside of the surface.
1604+
1605+ Damage is double-buffered state, see wl_surface.commit.
1606+
1607+ The damage rectangle is specified in surface-local coordinates,
1608+ where x and y specify the upper left corner of the damage rectangle.
1609+
1610+ The initial value for pending damage is empty: no damage.
1611+ wl_surface.damage adds pending damage: the new pending damage
1612+ is the union of old pending damage and the given rectangle.
1613+
1614+ wl_surface.commit assigns pending damage as the current damage,
1615+ and clears pending damage. The server will clear the current
1616+ damage as it repaints the surface.
1617+
1618+ Note! New clients should not use this request. Instead damage can be
1619+ posted with wl_surface.damage_buffer which uses buffer coordinates
1620+ instead of surface coordinates.
1621+ </description>
1622+ <arg name="x" type="int" summary="surface-local x coordinate"/>
1623+ <arg name="y" type="int" summary="surface-local y coordinate"/>
1624+ <arg name="width" type="int" summary="width of damage rectangle"/>
1625+ <arg name="height" type="int" summary="height of damage rectangle"/>
1626+ </request>
1627+
1628+ <request name="frame">
1629+ <description summary="request a frame throttling hint">
1630+ Request a notification when it is a good time to start drawing a new
1631+ frame, by creating a frame callback. This is useful for throttling
1632+ redrawing operations, and driving animations.
1633+
1634+ When a client is animating on a wl_surface, it can use the 'frame'
1635+ request to get notified when it is a good time to draw and commit the
1636+ next frame of animation. If the client commits an update earlier than
1637+ that, it is likely that some updates will not make it to the display,
1638+ and the client is wasting resources by drawing too often.
1639+
1640+ The frame request will take effect on the next wl_surface.commit.
1641+ The notification will only be posted for one frame unless
1642+ requested again. For a wl_surface, the notifications are posted in
1643+ the order the frame requests were committed.
1644+
1645+ The server must send the notifications so that a client
1646+ will not send excessive updates, while still allowing
1647+ the highest possible update rate for clients that wait for the reply
1648+ before drawing again. The server should give some time for the client
1649+ to draw and commit after sending the frame callback events to let it
1650+ hit the next output refresh.
1651+
1652+ A server should avoid signaling the frame callbacks if the
1653+ surface is not visible in any way, e.g. the surface is off-screen,
1654+ or completely obscured by other opaque surfaces.
1655+
1656+ The object returned by this request will be destroyed by the
1657+ compositor after the callback is fired and as such the client must not
1658+ attempt to use it after that point.
1659+
1660+ The callback_data passed in the callback is the current time, in
1661+ milliseconds, with an undefined base.
1662+ </description>
1663+ <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the frame request"/>
1664+ </request>
1665+
1666+ <request name="set_opaque_region">
1667+ <description summary="set opaque region">
1668+ This request sets the region of the surface that contains
1669+ opaque content.
1670+
1671+ The opaque region is an optimization hint for the compositor
1672+ that lets it optimize the redrawing of content behind opaque
1673+ regions. Setting an opaque region is not required for correct
1674+ behaviour, but marking transparent content as opaque will result
1675+ in repaint artifacts.
1676+
1677+ The opaque region is specified in surface-local coordinates.
1678+
1679+ The compositor ignores the parts of the opaque region that fall
1680+ outside of the surface.
1681+
1682+ Opaque region is double-buffered state, see wl_surface.commit.
1683+
1684+ wl_surface.set_opaque_region changes the pending opaque region.
1685+ wl_surface.commit copies the pending region to the current region.
1686+ Otherwise, the pending and current regions are never changed.
1687+
1688+ The initial value for an opaque region is empty. Setting the pending
1689+ opaque region has copy semantics, and the wl_region object can be
1690+ destroyed immediately. A NULL wl_region causes the pending opaque
1691+ region to be set to empty.
1692+ </description>
1693+ <arg name="region" type="object" interface="wl_region" allow-null="true"
1694+ summary="opaque region of the surface"/>
1695+ </request>
1696+
1697+ <request name="set_input_region">
1698+ <description summary="set input region">
1699+ This request sets the region of the surface that can receive
1700+ pointer and touch events.
1701+
1702+ Input events happening outside of this region will try the next
1703+ surface in the server surface stack. The compositor ignores the
1704+ parts of the input region that fall outside of the surface.
1705+
1706+ The input region is specified in surface-local coordinates.
1707+
1708+ Input region is double-buffered state, see wl_surface.commit.
1709+
1710+ wl_surface.set_input_region changes the pending input region.
1711+ wl_surface.commit copies the pending region to the current region.
1712+ Otherwise the pending and current regions are never changed,
1713+ except cursor and icon surfaces are special cases, see
1714+ wl_pointer.set_cursor and wl_data_device.start_drag.
1715+
1716+ The initial value for an input region is infinite. That means the
1717+ whole surface will accept input. Setting the pending input region
1718+ has copy semantics, and the wl_region object can be destroyed
1719+ immediately. A NULL wl_region causes the input region to be set
1720+ to infinite.
1721+ </description>
1722+ <arg name="region" type="object" interface="wl_region" allow-null="true"
1723+ summary="input region of the surface"/>
1724+ </request>
1725+
1726+ <request name="commit">
1727+ <description summary="commit pending surface state">
1728+ Surface state (input, opaque, and damage regions, attached buffers,
1729+ etc.) is double-buffered. Protocol requests modify the pending state,
1730+ as opposed to the active state in use by the compositor.
1731+
1732+ All requests that need a commit to become effective are documented
1733+ to affect double-buffered state.
1734+
1735+ Other interfaces may add further double-buffered surface state.
1736+
1737+ A commit request atomically creates a Content Update (CU) from the
1738+ pending state, even if the pending state has not been touched. The
1739+ content update is placed at the end of a per-surface queue until it
1740+ becomes active. After commit, the new pending state is as documented for
1741+ each related request.
1742+
1743+ A CU is either a Desync Content Update (DCU) or a Sync Content Update
1744+ (SCU). If the surface is effectively synchronized at the commit request,
1745+ it is a SCU, otherwise a DCU.
1746+
1747+ When a surface transitions from effectively synchronized to effectively
1748+ desynchronized, all SCUs in its queue which are not reachable by any
1749+ DCU become DCUs and dependency edges from outside the queue to these CUs
1750+ are removed.
1751+
1752+ See wl_subsurface for the definition of 'effectively synchronized' and
1753+ 'effectively desynchronized'.
1754+
1755+ When a CU is placed in the queue, the CU has a dependency on the CU in
1756+ front of it and to the SCU at end of the queue of every direct child
1757+ surface if that SCU exists and does not have another dependent. This can
1758+ form a directed acyclic graph of CUs with dependencies as edges.
1759+
1760+ In addition to surface state, the CU can have constraints that must be
1761+ satisfied before it can be applied. Other interfaces may add CU
1762+ constraints.
1763+
1764+ All DCUs which do not have a SCU in front of themselves in their queue,
1765+ are candidates. If the graph that's reachable by a candidate does not
1766+ have any unsatisfied constraints, the entire graph must be applied
1767+ atomically.
1768+
1769+ When a CU is applied, the wl_buffer is applied before all other state.
1770+ This means that all coordinates in double-buffered state are relative to
1771+ the newly attached wl_buffers, except for wl_surface.attach itself. If
1772+ there is no newly attached wl_buffer, the coordinates are relative to
1773+ the previous content update.
1774+ </description>
1775+ </request>
1776+
1777+ <event name="enter">
1778+ <description summary="surface enters an output">
1779+ This is emitted whenever a surface's creation, movement, or resizing
1780+ results in some part of it being within the scanout region of an
1781+ output.
1782+
1783+ Note that a surface may be overlapping with zero or more outputs.
1784+ </description>
1785+ <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
1786+ </event>
1787+
1788+ <event name="leave">
1789+ <description summary="surface leaves an output">
1790+ This is emitted whenever a surface's creation, movement, or resizing
1791+ results in it no longer having any part of it within the scanout region
1792+ of an output.
1793+
1794+ Clients should not use the number of outputs the surface is on for frame
1795+ throttling purposes. The surface might be hidden even if no leave event
1796+ has been sent, and the compositor might expect new surface content
1797+ updates even if no enter event has been sent. The frame event should be
1798+ used instead.
1799+ </description>
1800+ <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
1801+ </event>
1802+
1803+ <!-- Version 2 additions -->
1804+
1805+ <request name="set_buffer_transform" since="2">
1806+ <description summary="sets the buffer transformation">
1807+ This request sets the transformation that the client has already applied
1808+ to the content of the buffer. The accepted values for the transform
1809+ parameter are the values for wl_output.transform.
1810+
1811+ The compositor applies the inverse of this transformation whenever it
1812+ uses the buffer contents.
1813+
1814+ Buffer transform is double-buffered state, see wl_surface.commit.
1815+
1816+ A newly created surface has its buffer transformation set to normal.
1817+
1818+ wl_surface.set_buffer_transform changes the pending buffer
1819+ transformation. wl_surface.commit copies the pending buffer
1820+ transformation to the current one. Otherwise, the pending and current
1821+ values are never changed.
1822+
1823+ The purpose of this request is to allow clients to render content
1824+ according to the output transform, thus permitting the compositor to
1825+ use certain optimizations even if the display is rotated. Using
1826+ hardware overlays and scanning out a client buffer for fullscreen
1827+ surfaces are examples of such optimizations. Those optimizations are
1828+ highly dependent on the compositor implementation, so the use of this
1829+ request should be considered on a case-by-case basis.
1830+
1831+ Note that if the transform value includes 90 or 270 degree rotation,
1832+ the width of the buffer will become the surface height and the height
1833+ of the buffer will become the surface width.
1834+
1835+ If transform is not one of the values from the
1836+ wl_output.transform enum the invalid_transform protocol error
1837+ is raised.
1838+ </description>
1839+ <arg name="transform" type="int" enum="wl_output.transform"
1840+ summary="transform for interpreting buffer contents"/>
1841+ </request>
1842+
1843+ <!-- Version 3 additions -->
1844+
1845+ <request name="set_buffer_scale" since="3">
1846+ <description summary="sets the buffer scaling factor">
1847+ This request sets an optional scaling factor on how the compositor
1848+ interprets the contents of the buffer attached to the window.
1849+
1850+ Buffer scale is double-buffered state, see wl_surface.commit.
1851+
1852+ A newly created surface has its buffer scale set to 1.
1853+
1854+ wl_surface.set_buffer_scale changes the pending buffer scale.
1855+ wl_surface.commit copies the pending buffer scale to the current one.
1856+ Otherwise, the pending and current values are never changed.
1857+
1858+ The purpose of this request is to allow clients to supply higher
1859+ resolution buffer data for use on high resolution outputs. It is
1860+ intended that you pick the same buffer scale as the scale of the
1861+ output that the surface is displayed on. This means the compositor
1862+ can avoid scaling when rendering the surface on that output.
1863+
1864+ Note that if the scale is larger than 1, then you have to attach
1865+ a buffer that is larger (by a factor of scale in each dimension)
1866+ than the desired surface size.
1867+
1868+ If scale is not greater than 0 the invalid_scale protocol error is
1869+ raised.
1870+ </description>
1871+ <arg name="scale" type="int"
1872+ summary="scale for interpreting buffer contents"/>
1873+ </request>
1874+
1875+ <!-- Version 4 additions -->
1876+ <request name="damage_buffer" since="4">
1877+ <description summary="mark part of the surface damaged using buffer coordinates">
1878+ This request is used to describe the regions where the pending
1879+ buffer is different from the current surface contents, and where
1880+ the surface therefore needs to be repainted. The compositor
1881+ ignores the parts of the damage that fall outside of the surface.
1882+
1883+ Damage is double-buffered state, see wl_surface.commit.
1884+
1885+ The damage rectangle is specified in buffer coordinates,
1886+ where x and y specify the upper left corner of the damage rectangle.
1887+
1888+ The initial value for pending damage is empty: no damage.
1889+ wl_surface.damage_buffer adds pending damage: the new pending
1890+ damage is the union of old pending damage and the given rectangle.
1891+
1892+ wl_surface.commit assigns pending damage as the current damage,
1893+ and clears pending damage. The server will clear the current
1894+ damage as it repaints the surface.
1895+
1896+ This request differs from wl_surface.damage in only one way - it
1897+ takes damage in buffer coordinates instead of surface-local
1898+ coordinates. While this generally is more intuitive than surface
1899+ coordinates, it is especially desirable when using wp_viewport
1900+ or when a drawing library (like EGL) is unaware of buffer scale
1901+ and buffer transform.
1902+
1903+ Note: Because buffer transformation changes and damage requests may
1904+ be interleaved in the protocol stream, it is impossible to determine
1905+ the actual mapping between surface and buffer damage until
1906+ wl_surface.commit time. Therefore, compositors wishing to take both
1907+ kinds of damage into account will have to accumulate damage from the
1908+ two requests separately and only transform from one to the other
1909+ after receiving the wl_surface.commit.
1910+ </description>
1911+ <arg name="x" type="int" summary="buffer-local x coordinate"/>
1912+ <arg name="y" type="int" summary="buffer-local y coordinate"/>
1913+ <arg name="width" type="int" summary="width of damage rectangle"/>
1914+ <arg name="height" type="int" summary="height of damage rectangle"/>
1915+ </request>
1916+
1917+ <!-- Version 5 additions -->
1918+
1919+ <request name="offset" since="5">
1920+ <description summary="set the surface contents offset">
1921+ The x and y arguments specify the location of the new pending
1922+ buffer's upper left corner, relative to the current buffer's upper
1923+ left corner, in surface-local coordinates. In other words, the
1924+ x and y, combined with the new surface size define in which
1925+ directions the surface's size changes.
1926+
1927+ The exact semantics of wl_surface.offset are role-specific. Refer to
1928+ the documentation of specific roles for more information.
1929+
1930+ Surface location offset is double-buffered state, see
1931+ wl_surface.commit.
1932+
1933+ This request is semantically equivalent to and the replaces the x and y
1934+ arguments in the wl_surface.attach request in wl_surface versions prior
1935+ to 5. See wl_surface.attach for details.
1936+ </description>
1937+ <arg name="x" type="int" summary="surface-local x coordinate"/>
1938+ <arg name="y" type="int" summary="surface-local y coordinate"/>
1939+ </request>
1940+
1941+ <!-- Version 6 additions -->
1942+
1943+ <event name="preferred_buffer_scale" since="6">
1944+ <description summary="preferred buffer scale for the surface">
1945+ This event indicates the preferred buffer scale for this surface. It is
1946+ sent whenever the compositor's preference changes.
1947+
1948+ Before receiving this event the preferred buffer scale for this surface
1949+ is 1.
1950+
1951+ It is intended that scaling aware clients use this event to scale their
1952+ content and use wl_surface.set_buffer_scale to indicate the scale they
1953+ have rendered with. This allows clients to supply a higher detail
1954+ buffer.
1955+
1956+ The compositor shall emit a scale value greater than 0.
1957+ </description>
1958+ <arg name="factor" type="int" summary="preferred scaling factor"/>
1959+ </event>
1960+
1961+ <event name="preferred_buffer_transform" since="6">
1962+ <description summary="preferred buffer transform for the surface">
1963+ This event indicates the preferred buffer transform for this surface.
1964+ It is sent whenever the compositor's preference changes.
1965+
1966+ Before receiving this event the preferred buffer transform for this
1967+ surface is normal.
1968+
1969+ Applying this transformation to the surface buffer contents and using
1970+ wl_surface.set_buffer_transform might allow the compositor to use the
1971+ surface buffer more efficiently.
1972+ </description>
1973+ <arg name="transform" type="uint" enum="wl_output.transform"
1974+ summary="preferred transform"/>
1975+ </event>
1976+
1977+ <!-- Version 7 additions -->
1978+
1979+ <request name="get_release" since="7">
1980+ <description summary="get a release callback">
1981+ Create a callback for the release of the buffer attached by the client
1982+ with wl_surface.attach.
1983+
1984+ The compositor will release the buffer when it has finished its usage of
1985+ the underlying storage for the relevant commit. Once the client receives
1986+ this event, and assuming the associated buffer is not pending release
1987+ from other wl_surface.commit requests, the client can safely re-use the
1988+ buffer.
1989+
1990+ Release callbacks are double-buffered state, and will be associated
1991+ with the pending buffer at wl_surface.commit time.
1992+
1993+ The callback_data passed in the wl_callback.done event is unused and
1994+ is always zero.
1995+
1996+ Sending this request without attaching a non-null buffer in the same
1997+ content update is a protocol error. The compositor will send the
1998+ no_buffer error in this case.
1999+ </description>
2000+ <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the release"/>
2001+ </request>
2002+ </interface>
2003+
2004+ <interface name="wl_seat" version="11">
2005+ <description summary="group of input devices">
2006+ A seat is a group of keyboards, pointer and touch devices. This
2007+ object is published as a global during start up, or when such a
2008+ device is hot plugged. A seat typically has a pointer and
2009+ maintains a keyboard focus and a pointer focus.
2010+ </description>
2011+
2012+ <enum name="capability" bitfield="true">
2013+ <description summary="seat capability bitmask">
2014+ This is a bitmask of capabilities this seat has; if a member is
2015+ set, then it is present on the seat.
2016+ </description>
2017+ <entry name="pointer" value="1" summary="the seat has pointer devices"/>
2018+ <entry name="keyboard" value="2" summary="the seat has one or more keyboards"/>
2019+ <entry name="touch" value="4" summary="the seat has touch devices"/>
2020+ </enum>
2021+
2022+ <enum name="error">
2023+ <description summary="wl_seat error values">
2024+ These errors can be emitted in response to wl_seat requests.
2025+ </description>
2026+ <entry name="missing_capability" value="0"
2027+ summary="get_pointer, get_keyboard or get_touch called on seat without the matching capability"/>
2028+ </enum>
2029+
2030+ <event name="capabilities">
2031+ <description summary="seat capabilities changed">
2032+ This is sent on binding to the seat global or whenever a seat gains
2033+ or loses the pointer, keyboard or touch capabilities.
2034+ The argument is a capability enum containing the complete set of
2035+ capabilities this seat has.
2036+
2037+ When the pointer capability is added, a client may create a
2038+ wl_pointer object using the wl_seat.get_pointer request. This object
2039+ will receive pointer events until the capability is removed in the
2040+ future.
2041+
2042+ When the pointer capability is removed, a client should destroy the
2043+ wl_pointer objects associated with the seat where the capability was
2044+ removed, using the wl_pointer.release request. No further pointer
2045+ events will be received on these objects.
2046+
2047+ In some compositors, if a seat regains the pointer capability and a
2048+ client has a previously obtained wl_pointer object of version 4 or
2049+ less, that object may start sending pointer events again. This
2050+ behavior is considered a misinterpretation of the intended behavior
2051+ and must not be relied upon by the client. wl_pointer objects of
2052+ version 5 or later must not send events if created before the most
2053+ recent event notifying the client of an added pointer capability.
2054+
2055+ The above behavior also applies to wl_keyboard and wl_touch with the
2056+ keyboard and touch capabilities, respectively.
2057+ </description>
2058+ <arg name="capabilities" type="uint" enum="capability" summary="capabilities of the seat"/>
2059+ </event>
2060+
2061+ <request name="get_pointer">
2062+ <description summary="return pointer object">
2063+ The ID provided will be initialized to the wl_pointer interface
2064+ for this seat.
2065+
2066+ This request only takes effect if the seat has the pointer
2067+ capability, or has had the pointer capability in the past.
2068+ It is a protocol violation to issue this request on a seat that has
2069+ never had the pointer capability. The missing_capability error will
2070+ be sent in this case.
2071+ </description>
2072+ <arg name="id" type="new_id" interface="wl_pointer" summary="seat pointer"/>
2073+ </request>
2074+
2075+ <request name="get_keyboard">
2076+ <description summary="return keyboard object">
2077+ The ID provided will be initialized to the wl_keyboard interface
2078+ for this seat.
2079+
2080+ This request only takes effect if the seat has the keyboard
2081+ capability, or has had the keyboard capability in the past.
2082+ It is a protocol violation to issue this request on a seat that has
2083+ never had the keyboard capability. The missing_capability error will
2084+ be sent in this case.
2085+ </description>
2086+ <arg name="id" type="new_id" interface="wl_keyboard" summary="seat keyboard"/>
2087+ </request>
2088+
2089+ <request name="get_touch">
2090+ <description summary="return touch object">
2091+ The ID provided will be initialized to the wl_touch interface
2092+ for this seat.
2093+
2094+ This request only takes effect if the seat has the touch
2095+ capability, or has had the touch capability in the past.
2096+ It is a protocol violation to issue this request on a seat that has
2097+ never had the touch capability. The missing_capability error will
2098+ be sent in this case.
2099+ </description>
2100+ <arg name="id" type="new_id" interface="wl_touch" summary="seat touch interface"/>
2101+ </request>
2102+
2103+ <!-- Version 2 additions -->
2104+
2105+ <event name="name" since="2">
2106+ <description summary="unique identifier for this seat">
2107+ In a multi-seat configuration the seat name can be used by clients to
2108+ help identify which physical devices the seat represents.
2109+
2110+ The seat name is a UTF-8 string with no convention defined for its
2111+ contents. Each name is unique among all wl_seat globals. The name is
2112+ only guaranteed to be unique for the current compositor instance.
2113+
2114+ The same seat names are used for all clients. Thus, the name can be
2115+ shared across processes to refer to a specific wl_seat global.
2116+
2117+ The name event is sent after binding to the seat global, and should be sent
2118+ before announcing capabilities. This event is only sent once per seat object,
2119+ and the name does not change over the lifetime of the wl_seat global.
2120+
2121+ Compositors may re-use the same seat name if the wl_seat global is
2122+ destroyed and re-created later.
2123+ </description>
2124+ <arg name="name" type="string" summary="seat identifier"/>
2125+ </event>
2126+
2127+ <!-- Version 5 additions -->
2128+
2129+ <request name="release" type="destructor" since="5">
2130+ <description summary="release the seat object">
2131+ Using this request a client can tell the server that it is not going to
2132+ use the seat object anymore.
2133+ </description>
2134+ </request>
2135+
2136+ </interface>
2137+
2138+ <interface name="wl_pointer" version="11">
2139+ <description summary="pointer input device">
2140+ The wl_pointer interface represents one or more input devices,
2141+ such as mice, which control the pointer location and pointer_focus
2142+ of a seat.
2143+
2144+ The wl_pointer interface generates motion, enter and leave
2145+ events for the surfaces that the pointer is located over,
2146+ and button and axis events for button presses, button releases
2147+ and scrolling.
2148+ </description>
2149+
2150+ <enum name="error">
2151+ <entry name="role" value="0" summary="given wl_surface has another role"/>
2152+ </enum>
2153+
2154+ <request name="set_cursor">
2155+ <description summary="set the pointer surface">
2156+ Set the pointer surface, i.e., the surface that contains the
2157+ pointer image (cursor). This request gives the surface the role
2158+ of a cursor. If the surface already has another role, it raises
2159+ a protocol error.
2160+
2161+ The cursor actually changes only if the pointer
2162+ focus for this device is one of the requesting client's surfaces
2163+ or the surface parameter is the current pointer surface. If
2164+ there was a previous surface set with this request it is
2165+ replaced. If surface is NULL, the pointer image is hidden.
2166+
2167+ The parameters hotspot_x and hotspot_y define the position of
2168+ the pointer surface relative to the pointer location. Its
2169+ top-left corner is always at (x, y) - (hotspot_x, hotspot_y),
2170+ where (x, y) are the coordinates of the pointer location, in
2171+ surface-local coordinates.
2172+
2173+ On wl_surface.offset requests to the pointer surface, hotspot_x
2174+ and hotspot_y are decremented by the x and y parameters
2175+ passed to the request. The offset must be applied by
2176+ wl_surface.commit as usual.
2177+
2178+ The hotspot can also be updated by passing the currently set
2179+ pointer surface to this request with new values for hotspot_x
2180+ and hotspot_y.
2181+
2182+ The input region is ignored for wl_surfaces with the role of
2183+ a cursor. When the use as a cursor ends, the wl_surface is
2184+ unmapped.
2185+
2186+ The serial parameter must match the latest wl_pointer.enter
2187+ serial number sent to the client. Otherwise the request will be
2188+ ignored.
2189+ </description>
2190+ <arg name="serial" type="uint" summary="serial number of the enter event"/>
2191+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"
2192+ summary="pointer surface"/>
2193+ <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
2194+ <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
2195+ </request>
2196+
2197+ <event name="enter">
2198+ <description summary="enter event">
2199+ Notification that this seat's pointer is focused on a certain
2200+ surface.
2201+
2202+ When a seat's focus enters a surface, the pointer image
2203+ is undefined and a client should respond to this event by setting
2204+ an appropriate pointer image with the set_cursor request.
2205+ </description>
2206+ <arg name="serial" type="uint" summary="serial number of the enter event"/>
2207+ <arg name="surface" type="object" interface="wl_surface" summary="surface entered by the pointer"/>
2208+ <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2209+ <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2210+ </event>
2211+
2212+ <event name="leave">
2213+ <description summary="leave event">
2214+ Notification that this seat's pointer is no longer focused on
2215+ a certain surface.
2216+
2217+ The leave notification is sent before the enter notification
2218+ for the new focus.
2219+ </description>
2220+ <arg name="serial" type="uint" summary="serial number of the leave event"/>
2221+ <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
2222+ </event>
2223+
2224+ <event name="motion">
2225+ <description summary="pointer motion event">
2226+ Notification of pointer location change. The arguments
2227+ surface_x and surface_y are the location relative to the
2228+ focused surface.
2229+ </description>
2230+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2231+ <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2232+ <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2233+ </event>
2234+
2235+ <enum name="button_state">
2236+ <description summary="physical button state">
2237+ Describes the physical state of a button that produced the button
2238+ event.
2239+ </description>
2240+ <entry name="released" value="0" summary="the button is not pressed"/>
2241+ <entry name="pressed" value="1" summary="the button is pressed"/>
2242+ </enum>
2243+
2244+ <event name="button">
2245+ <description summary="pointer button event">
2246+ Mouse button click and release notifications.
2247+
2248+ The location of the click is given by the last motion, warp or
2249+ enter event.
2250+ The time argument is a timestamp with millisecond
2251+ granularity, with an undefined base.
2252+
2253+ The button is a button code as defined in the Linux kernel's
2254+ linux/input-event-codes.h header file, e.g. BTN_LEFT.
2255+
2256+ Any 16-bit button code value is reserved for future additions to the
2257+ kernel's event code list. All other button codes above 0xFFFF are
2258+ currently undefined but may be used in future versions of this
2259+ protocol.
2260+ </description>
2261+ <arg name="serial" type="uint" summary="serial number of the button event"/>
2262+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2263+ <arg name="button" type="uint" summary="button that produced the event"/>
2264+ <arg name="state" type="uint" enum="button_state" summary="physical state of the button"/>
2265+ </event>
2266+
2267+ <enum name="axis">
2268+ <description summary="axis types">
2269+ Describes the axis types of scroll events.
2270+ </description>
2271+ <entry name="vertical_scroll" value="0" summary="vertical axis"/>
2272+ <entry name="horizontal_scroll" value="1" summary="horizontal axis"/>
2273+ </enum>
2274+
2275+ <event name="axis">
2276+ <description summary="axis event">
2277+ Scroll and other axis notifications.
2278+
2279+ For scroll events (vertical and horizontal scroll axes), the
2280+ value parameter is the length of a vector along the specified
2281+ axis in a coordinate space identical to those of motion events,
2282+ representing a relative movement along the specified axis.
2283+
2284+ For devices that support movements non-parallel to axes multiple
2285+ axis events will be emitted.
2286+
2287+ When applicable, for example for touch pads, the server can
2288+ choose to emit scroll events where the motion vector is
2289+ equivalent to a motion event vector.
2290+
2291+ When applicable, a client can transform its content relative to the
2292+ scroll distance.
2293+ </description>
2294+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2295+ <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2296+ <arg name="value" type="fixed" summary="length of vector in surface-local coordinate space"/>
2297+ </event>
2298+
2299+ <!-- Version 3 additions -->
2300+
2301+ <request name="release" type="destructor" since="3">
2302+ <description summary="release the pointer object">
2303+ Using this request a client can tell the server that it is not going to
2304+ use the pointer object anymore.
2305+
2306+ This request destroys the pointer proxy object, so clients must not call
2307+ wl_pointer_destroy() after using this request.
2308+ </description>
2309+ </request>
2310+
2311+ <!-- Version 5 additions -->
2312+
2313+ <event name="frame" since="5">
2314+ <description summary="end of a pointer event sequence">
2315+ Indicates the end of a set of events that logically belong together.
2316+ A client is expected to accumulate the data in all events within the
2317+ frame before proceeding.
2318+
2319+ All wl_pointer events before a wl_pointer.frame event belong
2320+ logically together. For example, in a diagonal scroll motion the
2321+ compositor will send an optional wl_pointer.axis_source event, two
2322+ wl_pointer.axis events (horizontal and vertical) and finally a
2323+ wl_pointer.frame event. The client may use this information to
2324+ calculate a diagonal vector for scrolling.
2325+
2326+ When multiple wl_pointer.axis events occur within the same frame,
2327+ the motion vector is the combined motion of all events.
2328+ When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
2329+ the same frame, this indicates that axis movement in one axis has
2330+ stopped but continues in the other axis.
2331+ When multiple wl_pointer.axis_stop events occur within the same
2332+ frame, this indicates that these axes stopped in the same instance.
2333+
2334+ A wl_pointer.frame event is sent for every logical event group,
2335+ even if the group only contains a single wl_pointer event.
2336+ Specifically, a client may get a sequence: motion, frame, button,
2337+ frame, axis, frame, axis_stop, frame.
2338+
2339+ The wl_pointer.enter and wl_pointer.leave events are logical events
2340+ generated by the compositor and not the hardware. These events are
2341+ also grouped by a wl_pointer.frame. When a pointer moves from one
2342+ surface to another, a compositor should group the
2343+ wl_pointer.leave event within the same wl_pointer.frame.
2344+ However, a client must not rely on wl_pointer.leave and
2345+ wl_pointer.enter being in the same wl_pointer.frame.
2346+ Compositor-specific policies may require the wl_pointer.leave and
2347+ wl_pointer.enter event being split across multiple wl_pointer.frame
2348+ groups.
2349+ </description>
2350+ </event>
2351+
2352+ <enum name="axis_source">
2353+ <description summary="axis source types">
2354+ Describes the source types for axis events. This indicates to the
2355+ client how an axis event was physically generated; a client may
2356+ adjust the user interface accordingly. For example, scroll events
2357+ from a "finger" source may be in a smooth coordinate space with
2358+ kinetic scrolling whereas a "wheel" source may be in discrete steps
2359+ of a number of lines.
2360+
2361+ The "continuous" axis source is a device generating events in a
2362+ continuous coordinate space, but using something other than a
2363+ finger. One example for this source is button-based scrolling where
2364+ the vertical motion of a device is converted to scroll events while
2365+ a button is held down.
2366+
2367+ The "wheel tilt" axis source indicates that the actual device is a
2368+ wheel but the scroll event is not caused by a rotation but a
2369+ (usually sideways) tilt of the wheel.
2370+ </description>
2371+ <entry name="wheel" value="0" summary="a physical wheel rotation" />
2372+ <entry name="finger" value="1" summary="finger on a touch surface" />
2373+ <entry name="continuous" value="2" summary="continuous coordinate space"/>
2374+ <entry name="wheel_tilt" value="3" summary="a physical wheel tilt" since="6"/>
2375+ </enum>
2376+
2377+ <event name="axis_source" since="5">
2378+ <description summary="axis source event">
2379+ Source information for scroll and other axes.
2380+
2381+ This event does not occur on its own. It is sent before a
2382+ wl_pointer.frame event and carries the source information for
2383+ all events within that frame.
2384+
2385+ The source specifies how this event was generated. If the source is
2386+ wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
2387+ sent when the user lifts the finger off the device.
2388+
2389+ If the source is wl_pointer.axis_source.wheel,
2390+ wl_pointer.axis_source.wheel_tilt or
2391+ wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
2392+ or may not be sent. Whether a compositor sends an axis_stop event
2393+ for these sources is hardware-specific and implementation-dependent;
2394+ clients must not rely on receiving an axis_stop event for these
2395+ scroll sources and should treat scroll sequences from these scroll
2396+ sources as unterminated by default.
2397+
2398+ This event is optional. If the source is unknown for a particular
2399+ axis event sequence, no event is sent.
2400+ Only one wl_pointer.axis_source event is permitted per frame.
2401+
2402+ The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2403+ not guaranteed.
2404+ </description>
2405+ <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
2406+ </event>
2407+
2408+ <event name="axis_stop" since="5">
2409+ <description summary="axis stop event">
2410+ Stop notification for scroll and other axes.
2411+
2412+ For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
2413+ is sent to notify a client that the axis sequence has terminated.
2414+ This enables the client to implement kinetic scrolling.
2415+ See the wl_pointer.axis_source documentation for information on when
2416+ this event may be generated.
2417+
2418+ Any wl_pointer.axis events with the same axis_source after this
2419+ event should be considered as the start of a new axis motion.
2420+
2421+ The timestamp is to be interpreted identical to the timestamp in the
2422+ wl_pointer.axis event. The timestamp value may be the same as a
2423+ preceding wl_pointer.axis event.
2424+ </description>
2425+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2426+ <arg name="axis" type="uint" enum="axis" summary="the axis stopped with this event"/>
2427+ </event>
2428+
2429+ <event name="axis_discrete" since="5" deprecated-since="8">
2430+ <description summary="axis click event">
2431+ Discrete step information for scroll and other axes.
2432+
2433+ This event carries the axis value of the wl_pointer.axis event in
2434+ discrete steps (e.g. mouse wheel clicks).
2435+
2436+ This event is deprecated with wl_pointer version 8 - this event is not
2437+ sent to clients supporting version 8 or later.
2438+
2439+ This event does not occur on its own, it is coupled with a
2440+ wl_pointer.axis event that represents this axis value on a
2441+ continuous scale. The protocol guarantees that each axis_discrete
2442+ event is always followed by exactly one axis event with the same
2443+ axis number within the same wl_pointer.frame. Note that the protocol
2444+ allows for other events to occur between the axis_discrete and
2445+ its coupled axis event, including other axis_discrete or axis
2446+ events. A wl_pointer.frame must not contain more than one axis_discrete
2447+ event per axis type.
2448+
2449+ This event is optional; continuous scrolling devices
2450+ like two-finger scrolling on touchpads do not have discrete
2451+ steps and do not generate this event.
2452+
2453+ The discrete value carries the directional information. e.g. a value
2454+ of -2 is two steps towards the negative direction of this axis.
2455+
2456+ The axis number is identical to the axis number in the associated
2457+ axis event.
2458+
2459+ The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2460+ not guaranteed.
2461+ </description>
2462+ <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2463+ <arg name="discrete" type="int" summary="number of steps"/>
2464+ </event>
2465+
2466+ <event name="axis_value120" since="8">
2467+ <description summary="axis high-resolution scroll event">
2468+ Discrete high-resolution scroll information.
2469+
2470+ This event carries high-resolution wheel scroll information,
2471+ with each multiple of 120 representing one logical scroll step
2472+ (a wheel detent). For example, an axis_value120 of 30 is one quarter of
2473+ a logical scroll step in the positive direction, a value120 of
2474+ -240 are two logical scroll steps in the negative direction within the
2475+ same hardware event.
2476+ Clients that rely on discrete scrolling should accumulate the
2477+ value120 to multiples of 120 before processing the event.
2478+
2479+ The value120 must not be zero.
2480+
2481+ This event replaces the wl_pointer.axis_discrete event in clients
2482+ supporting wl_pointer version 8 or later.
2483+
2484+ Where a wl_pointer.axis_source event occurs in the same
2485+ wl_pointer.frame, the axis source applies to this event.
2486+
2487+ The order of wl_pointer.axis_value120 and wl_pointer.axis_source is
2488+ not guaranteed.
2489+ </description>
2490+ <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2491+ <arg name="value120" type="int" summary="scroll distance as fraction of 120"/>
2492+ </event>
2493+
2494+ <!-- Version 9 additions -->
2495+
2496+ <enum name="axis_relative_direction">
2497+ <description summary="axis relative direction">
2498+ This specifies the direction of the physical motion that caused a
2499+ wl_pointer.axis event, relative to the wl_pointer.axis direction.
2500+ </description>
2501+ <entry name="identical" value="0"
2502+ summary="physical motion matches axis direction"/>
2503+ <entry name="inverted" value="1"
2504+ summary="physical motion is the inverse of the axis direction"/>
2505+ </enum>
2506+
2507+ <event name="axis_relative_direction" since="9">
2508+ <description summary="axis relative physical direction event">
2509+ Relative directional information of the entity causing the axis
2510+ motion.
2511+
2512+ For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
2513+ event specifies the movement direction of the entity causing the
2514+ wl_pointer.axis event. For example:
2515+ - if a user's fingers on a touchpad move down and this
2516+ causes a wl_pointer.axis vertical_scroll down event, the physical
2517+ direction is 'identical'
2518+ - if a user's fingers on a touchpad move down and this causes a
2519+ wl_pointer.axis vertical_scroll up scroll up event ('natural
2520+ scrolling'), the physical direction is 'inverted'.
2521+
2522+ A client may use this information to adjust scroll motion of
2523+ components. Specifically, enabling natural scrolling causes the
2524+ content to change direction compared to traditional scrolling.
2525+ Some widgets like volume control sliders should usually match the
2526+ physical direction regardless of whether natural scrolling is
2527+ active. This event enables clients to match the scroll direction of
2528+ a widget to the physical direction.
2529+
2530+ This event does not occur on its own, it is coupled with a
2531+ wl_pointer.axis event that represents this axis value.
2532+ The protocol guarantees that each axis_relative_direction event is
2533+ always followed by exactly one axis event with the same
2534+ axis number within the same wl_pointer.frame. Note that the protocol
2535+ allows for other events to occur between the axis_relative_direction
2536+ and its coupled axis event.
2537+
2538+ The axis number is identical to the axis number in the associated
2539+ axis event.
2540+
2541+ The order of wl_pointer.axis_relative_direction,
2542+ wl_pointer.axis_discrete and wl_pointer.axis_source is not
2543+ guaranteed.
2544+ </description>
2545+ <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2546+ <arg name="direction" type="uint" enum="axis_relative_direction"
2547+ summary="physical direction relative to axis motion"/>
2548+ </event>
2549+
2550+ <!-- Version 11 additions -->
2551+
2552+ <event name="warp" since="11">
2553+ <description summary="pointer warp event">
2554+ Notification of pointer location change within a surface.
2555+
2556+ This location change is not due to events on the input device,
2557+ but because either the surface under the pointer was moved and
2558+ thus the relative position of the pointer changed, or because
2559+ the compositor changed the pointer position in response to an
2560+ event like pointer confinement being exited.
2561+
2562+ The arguments surface_x and surface_y are the location relative to
2563+ the focused surface.
2564+
2565+ This event must not occur in the same wl_pointer.frame as a
2566+ wl_pointer.enter or wl_pointer.motion event.
2567+ </description>
2568+ <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2569+ <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2570+ </event>
2571+ </interface>
2572+
2573+ <interface name="wl_keyboard" version="11">
2574+ <description summary="keyboard input device">
2575+ The wl_keyboard interface represents one or more keyboards
2576+ associated with a seat.
2577+
2578+ Each wl_keyboard has the following logical state:
2579+
2580+ - an active surface (possibly null),
2581+ - the keys currently logically down,
2582+ - the active modifiers,
2583+ - the active group.
2584+
2585+ By default, the active surface is null, the keys currently logically down
2586+ are empty, the active modifiers and the active group are 0.
2587+ </description>
2588+
2589+ <enum name="keymap_format">
2590+ <description summary="keyboard mapping format">
2591+ This specifies the format of the keymap provided to the
2592+ client with the wl_keyboard.keymap event.
2593+ </description>
2594+ <entry name="no_keymap" value="0"
2595+ summary="no keymap; client must understand how to interpret the raw keycode"/>
2596+ <entry name="xkb_v1" value="1"
2597+ summary="libxkbcommon compatible, null-terminated string; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
2598+ </enum>
2599+
2600+ <event name="keymap">
2601+ <description summary="keyboard mapping">
2602+ This event provides a file descriptor to the client which can be
2603+ memory-mapped in read-only mode to provide a keyboard mapping
2604+ description.
2605+
2606+ From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
2607+ the recipient, as MAP_SHARED may fail.
2608+ </description>
2609+ <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
2610+ <arg name="fd" type="fd" summary="keymap file descriptor"/>
2611+ <arg name="size" type="uint" summary="keymap size, in bytes"/>
2612+ </event>
2613+
2614+ <event name="enter">
2615+ <description summary="enter event">
2616+ Notification that this seat's keyboard focus is on a certain
2617+ surface.
2618+
2619+ The compositor must send the wl_keyboard.modifiers event after this
2620+ event.
2621+
2622+ In the wl_keyboard logical state, this event sets the active surface to
2623+ the surface argument and the keys currently logically down to the keys
2624+ in the keys argument. The compositor must not send this event if the
2625+ wl_keyboard already had an active surface immediately before this event.
2626+
2627+ Clients should not use the list of pressed keys to emulate key-press
2628+ events. The order of keys in the list is unspecified.
2629+ </description>
2630+ <arg name="serial" type="uint" summary="serial number of the enter event"/>
2631+ <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
2632+ <arg name="keys" type="array" summary="the keys currently logically down"/>
2633+ </event>
2634+
2635+ <event name="leave">
2636+ <description summary="leave event">
2637+ Notification that this seat's keyboard focus is no longer on
2638+ a certain surface.
2639+
2640+ The leave notification is sent before the enter notification
2641+ for the new focus.
2642+
2643+ In the wl_keyboard logical state, this event resets all values to their
2644+ defaults. The compositor must not send this event if the active surface
2645+ of the wl_keyboard was not equal to the surface argument immediately
2646+ before this event.
2647+ </description>
2648+ <arg name="serial" type="uint" summary="serial number of the leave event"/>
2649+ <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
2650+ </event>
2651+
2652+ <enum name="key_state">
2653+ <description summary="physical key state">
2654+ Describes the physical state of a key that produced the key event.
2655+
2656+ Since version 10, the key can be in a "repeated" pseudo-state which
2657+ means the same as "pressed", but is used to signal repetition in the
2658+ key event.
2659+
2660+ The key may only enter the repeated state after entering the pressed
2661+ state and before entering the released state. This event may be
2662+ generated multiple times while the key is down.
2663+ </description>
2664+ <entry name="released" value="0" summary="key is not pressed"/>
2665+ <entry name="pressed" value="1" summary="key is pressed"/>
2666+ <entry name="repeated" value="2" summary="key was repeated" since="10"/>
2667+ </enum>
2668+
2669+ <event name="key">
2670+ <description summary="key event">
2671+ A key was pressed or released.
2672+ The time argument is a timestamp with millisecond
2673+ granularity, with an undefined base.
2674+
2675+ The key is a platform-specific key code that can be interpreted
2676+ by feeding it to the keyboard mapping (see the keymap event).
2677+
2678+ If this event produces a change in modifiers, then the resulting
2679+ wl_keyboard.modifiers event must be sent after this event.
2680+
2681+ In the wl_keyboard logical state, this event adds the key to the keys
2682+ currently logically down (if the state argument is pressed) or removes
2683+ the key from the keys currently logically down (if the state argument is
2684+ released). The compositor must not send this event if the wl_keyboard
2685+ did not have an active surface immediately before this event. The
2686+ compositor must not send this event if state is pressed (resp. released)
2687+ and the key was already logically down (resp. was not logically down)
2688+ immediately before this event.
2689+
2690+ Since version 10, compositors may send key events with the "repeated"
2691+ key state when a wl_keyboard.repeat_info event with a rate argument of
2692+ 0 has been received. This allows the compositor to take over the
2693+ responsibility of key repetition.
2694+ </description>
2695+ <arg name="serial" type="uint" summary="serial number of the key event"/>
2696+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2697+ <arg name="key" type="uint" summary="key that produced the event"/>
2698+ <arg name="state" type="uint" enum="key_state" summary="physical state of the key"/>
2699+ </event>
2700+
2701+ <event name="modifiers">
2702+ <description summary="modifier and group state">
2703+ Notifies clients that the modifier and/or group state has
2704+ changed, and it should update its local state.
2705+
2706+ The compositor may send this event without a surface of the client
2707+ having keyboard focus, for example to tie modifier information to
2708+ pointer focus instead. If a modifier event with pressed modifiers is sent
2709+ without a prior enter event, the client can assume the modifier state is
2710+ valid until it receives the next wl_keyboard.modifiers event. In order to
2711+ reset the modifier state again, the compositor can send a
2712+ wl_keyboard.modifiers event with no pressed modifiers.
2713+
2714+ In the wl_keyboard logical state, this event updates the modifiers and
2715+ group.
2716+ </description>
2717+ <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
2718+ <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
2719+ <arg name="mods_latched" type="uint" summary="latched modifiers"/>
2720+ <arg name="mods_locked" type="uint" summary="locked modifiers"/>
2721+ <arg name="group" type="uint" summary="keyboard layout"/>
2722+ </event>
2723+
2724+ <!-- Version 3 additions -->
2725+
2726+ <request name="release" type="destructor" since="3">
2727+ <description summary="release the keyboard object"/>
2728+ </request>
2729+
2730+ <!-- Version 4 additions -->
2731+
2732+ <event name="repeat_info" since="4">
2733+ <description summary="repeat rate and delay">
2734+ Informs the client about the keyboard's repeat rate and delay.
2735+
2736+ This event is sent as soon as the wl_keyboard object has been created,
2737+ and is guaranteed to be received by the client before any key press
2738+ event.
2739+
2740+ Negative values for either rate or delay are illegal. A rate of zero
2741+ will disable any repeating (regardless of the value of delay).
2742+
2743+ This event can be sent later on as well with a new value if necessary,
2744+ so clients should continue listening for the event past the creation
2745+ of wl_keyboard.
2746+ </description>
2747+ <arg name="rate" type="int"
2748+ summary="the rate of repeating keys in characters per second"/>
2749+ <arg name="delay" type="int"
2750+ summary="delay in milliseconds since key down until repeating starts"/>
2751+ </event>
2752+ </interface>
2753+
2754+ <interface name="wl_touch" version="11">
2755+ <description summary="touchscreen input device">
2756+ The wl_touch interface represents a touchscreen
2757+ associated with a seat.
2758+
2759+ Touch interactions can consist of one or more contacts.
2760+ For each contact, a series of events is generated, starting
2761+ with a down event, followed by zero or more motion events,
2762+ and ending with an up event. Events relating to the same
2763+ contact point can be identified by the ID of the sequence.
2764+ </description>
2765+
2766+ <event name="down">
2767+ <description summary="touch down event and beginning of a touch sequence">
2768+ A new touch point has appeared on the surface. This touch point is
2769+ assigned a unique ID. Future events from this touch point reference
2770+ this ID. The ID ceases to be valid after a touch up event and may be
2771+ reused in the future.
2772+ </description>
2773+ <arg name="serial" type="uint" summary="serial number of the touch down event"/>
2774+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2775+ <arg name="surface" type="object" interface="wl_surface" summary="surface touched"/>
2776+ <arg name="id" type="int" summary="the unique ID of this touch point"/>
2777+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2778+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2779+ </event>
2780+
2781+ <event name="up">
2782+ <description summary="end of a touch event sequence">
2783+ The touch point has disappeared. No further events will be sent for
2784+ this touch point and the touch point's ID is released and may be
2785+ reused in a future touch down event.
2786+ </description>
2787+ <arg name="serial" type="uint" summary="serial number of the touch up event"/>
2788+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2789+ <arg name="id" type="int" summary="the unique ID of this touch point"/>
2790+ </event>
2791+
2792+ <event name="motion">
2793+ <description summary="update of touch point coordinates">
2794+ A touch point has changed coordinates.
2795+ </description>
2796+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2797+ <arg name="id" type="int" summary="the unique ID of this touch point"/>
2798+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2799+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2800+ </event>
2801+
2802+ <event name="frame">
2803+ <description summary="end of touch frame event">
2804+ Indicates the end of a set of events that logically belong together.
2805+ A client is expected to accumulate the data in all events within the
2806+ frame before proceeding.
2807+
2808+ A wl_touch.frame terminates at least one event but otherwise no
2809+ guarantee is provided about the set of events within a frame. A client
2810+ must assume that any state not updated in a frame is unchanged from the
2811+ previously known state.
2812+ </description>
2813+ </event>
2814+
2815+ <event name="cancel">
2816+ <description summary="touch session cancelled">
2817+ Sent if the compositor decides the touch stream is a global
2818+ gesture. No further events are sent to the clients from that
2819+ particular gesture. Touch cancellation applies to all touch points
2820+ currently active on this client's surface. The client is
2821+ responsible for finalizing the touch points, future touch points on
2822+ this surface may reuse the touch point ID.
2823+
2824+ No frame event is required after the cancel event.
2825+ </description>
2826+ </event>
2827+
2828+ <!-- Version 3 additions -->
2829+
2830+ <request name="release" type="destructor" since="3">
2831+ <description summary="release the touch object"/>
2832+ </request>
2833+
2834+ <!-- Version 6 additions -->
2835+
2836+ <event name="shape" since="6">
2837+ <description summary="update shape of touch point">
2838+ Sent when a touchpoint has changed its shape.
2839+
2840+ This event does not occur on its own. It is sent before a
2841+ wl_touch.frame event and carries the new shape information for
2842+ any previously reported, or new touch points of that frame.
2843+
2844+ Other events describing the touch point such as wl_touch.down,
2845+ wl_touch.motion or wl_touch.orientation may be sent within the
2846+ same wl_touch.frame. A client should treat these events as a single
2847+ logical touch point update. The order of wl_touch.shape,
2848+ wl_touch.orientation and wl_touch.motion is not guaranteed.
2849+ A wl_touch.down event is guaranteed to occur before the first
2850+ wl_touch.shape event for this touch ID but both events may occur within
2851+ the same wl_touch.frame.
2852+
2853+ A touchpoint shape is approximated by an ellipse through the major and
2854+ minor axis length. The major axis length describes the longer diameter
2855+ of the ellipse, while the minor axis length describes the shorter
2856+ diameter. Major and minor are orthogonal and both are specified in
2857+ surface-local coordinates. The center of the ellipse is always at the
2858+ touchpoint location as reported by wl_touch.down or wl_touch.motion.
2859+
2860+ This event is only sent by the compositor if the touch device supports
2861+ shape reports. The client has to make reasonable assumptions about the
2862+ shape if it did not receive this event.
2863+ </description>
2864+ <arg name="id" type="int" summary="the unique ID of this touch point"/>
2865+ <arg name="major" type="fixed" summary="length of the major axis in surface-local coordinates"/>
2866+ <arg name="minor" type="fixed" summary="length of the minor axis in surface-local coordinates"/>
2867+ </event>
2868+
2869+ <event name="orientation" since="6">
2870+ <description summary="update orientation of touch point">
2871+ Sent when a touchpoint has changed its orientation.
2872+
2873+ This event does not occur on its own. It is sent before a
2874+ wl_touch.frame event and carries the new shape information for
2875+ any previously reported, or new touch points of that frame.
2876+
2877+ Other events describing the touch point such as wl_touch.down,
2878+ wl_touch.motion or wl_touch.shape may be sent within the
2879+ same wl_touch.frame. A client should treat these events as a single
2880+ logical touch point update. The order of wl_touch.shape,
2881+ wl_touch.orientation and wl_touch.motion is not guaranteed.
2882+ A wl_touch.down event is guaranteed to occur before the first
2883+ wl_touch.orientation event for this touch ID but both events may occur
2884+ within the same wl_touch.frame.
2885+
2886+ The orientation describes the clockwise angle of a touchpoint's major
2887+ axis to the positive surface y-axis and is normalized to the -180 to
2888+ +180 degree range. The granularity of orientation depends on the touch
2889+ device, some devices only support binary rotation values between 0 and
2890+ 90 degrees.
2891+
2892+ This event is only sent by the compositor if the touch device supports
2893+ orientation reports.
2894+ </description>
2895+ <arg name="id" type="int" summary="the unique ID of this touch point"/>
2896+ <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
2897+ </event>
2898+ </interface>
2899+
2900+ <interface name="wl_output" version="4">
2901+ <description summary="compositor output region">
2902+ An output describes part of the compositor geometry. The
2903+ compositor works in the 'compositor coordinate system' and an
2904+ output corresponds to a rectangular area in that space that is
2905+ actually visible. This typically corresponds to a monitor that
2906+ displays part of the compositor space. This object is published
2907+ as global during start up, or when a monitor is hotplugged.
2908+ </description>
2909+
2910+ <enum name="subpixel">
2911+ <description summary="subpixel geometry information">
2912+ This enumeration describes how the physical
2913+ pixels on an output are laid out.
2914+ </description>
2915+ <entry name="unknown" value="0" summary="unknown geometry"/>
2916+ <entry name="none" value="1" summary="no geometry"/>
2917+ <entry name="horizontal_rgb" value="2" summary="horizontal RGB"/>
2918+ <entry name="horizontal_bgr" value="3" summary="horizontal BGR"/>
2919+ <entry name="vertical_rgb" value="4" summary="vertical RGB"/>
2920+ <entry name="vertical_bgr" value="5" summary="vertical BGR"/>
2921+ </enum>
2922+
2923+ <enum name="transform">
2924+ <description summary="transformation applied to buffer contents">
2925+ This describes transformations that clients and compositors apply to
2926+ buffer contents.
2927+
2928+ The flipped values correspond to an initial flip around a
2929+ vertical axis followed by rotation.
2930+
2931+ The purpose is mainly to allow clients to render accordingly and
2932+ tell the compositor, so that for fullscreen surfaces, the
2933+ compositor will still be able to scan out directly from client
2934+ surfaces.
2935+ </description>
2936+ <entry name="normal" value="0" summary="no transform"/>
2937+ <entry name="90" value="1" summary="90 degrees counter-clockwise"/>
2938+ <entry name="180" value="2" summary="180 degrees counter-clockwise"/>
2939+ <entry name="270" value="3" summary="270 degrees counter-clockwise"/>
2940+ <entry name="flipped" value="4" summary="180 degree flip around a vertical axis"/>
2941+ <entry name="flipped_90" value="5" summary="flip and rotate 90 degrees counter-clockwise"/>
2942+ <entry name="flipped_180" value="6" summary="flip and rotate 180 degrees counter-clockwise"/>
2943+ <entry name="flipped_270" value="7" summary="flip and rotate 270 degrees counter-clockwise"/>
2944+ </enum>
2945+
2946+ <event name="geometry">
2947+ <description summary="properties of the output">
2948+ The geometry event describes geometric properties of the output.
2949+ The event is sent when binding to the output object and whenever
2950+ any of the properties change.
2951+
2952+ The physical size can be set to zero if it doesn't make sense for this
2953+ output (e.g. for projectors or virtual outputs).
2954+
2955+ The geometry event will be followed by a done event (starting from
2956+ version 2).
2957+
2958+ Clients should use wl_surface.preferred_buffer_transform instead of the
2959+ transform advertised by this event to find the preferred buffer
2960+ transform to use for a surface.
2961+
2962+ Note: wl_output only advertises partial information about the output
2963+ position and identification. Some compositors, for instance those not
2964+ implementing a desktop-style output layout or those exposing virtual
2965+ outputs, might fake this information. Instead of using x and y, clients
2966+ should use xdg_output.logical_position. Instead of using make and model,
2967+ clients should use name and description.
2968+ </description>
2969+ <arg name="x" type="int"
2970+ summary="x position within the global compositor space"/>
2971+ <arg name="y" type="int"
2972+ summary="y position within the global compositor space"/>
2973+ <arg name="physical_width" type="int"
2974+ summary="width in millimeters of the output"/>
2975+ <arg name="physical_height" type="int"
2976+ summary="height in millimeters of the output"/>
2977+ <arg name="subpixel" type="int" enum="subpixel"
2978+ summary="subpixel orientation of the output"/>
2979+ <arg name="make" type="string"
2980+ summary="textual description of the manufacturer"/>
2981+ <arg name="model" type="string"
2982+ summary="textual description of the model"/>
2983+ <arg name="transform" type="int" enum="transform"
2984+ summary="additional transformation applied to buffer contents during presentation"/>
2985+ </event>
2986+
2987+ <enum name="mode" bitfield="true">
2988+ <description summary="mode information">
2989+ These flags describe properties of an output mode.
2990+ They are used in the flags bitfield of the mode event.
2991+ </description>
2992+ <entry name="current" value="0x1"
2993+ summary="indicates this is the current mode"/>
2994+ <entry name="preferred" value="0x2"
2995+ summary="indicates this is the preferred mode"/>
2996+ </enum>
2997+
2998+ <event name="mode">
2999+ <description summary="advertise available modes for the output">
3000+ The mode event describes an available mode for the output.
3001+
3002+ The event is sent when binding to the output object and there
3003+ will always be one mode, the current mode. The event is sent
3004+ again if an output changes mode, for the mode that is now
3005+ current. In other words, the current mode is always the last
3006+ mode that was received with the current flag set.
3007+
3008+ Non-current modes are deprecated. A compositor can decide to only
3009+ advertise the current mode and never send other modes. Clients
3010+ should not rely on non-current modes.
3011+
3012+ The size of a mode is given in physical hardware units of
3013+ the output device. This is not necessarily the same as
3014+ the output size in the global compositor space. For instance,
3015+ the output may be scaled, as described in wl_output.scale,
3016+ or transformed, as described in wl_output.transform. Clients
3017+ willing to retrieve the output size in the global compositor
3018+ space should use xdg_output.logical_size instead.
3019+
3020+ The vertical refresh rate can be set to zero if it doesn't make
3021+ sense for this output (e.g. for virtual outputs).
3022+
3023+ The mode event will be followed by a done event (starting from
3024+ version 2).
3025+
3026+ Clients should not use the refresh rate to schedule frames. Instead,
3027+ they should use the wl_surface.frame event or the presentation-time
3028+ protocol.
3029+
3030+ Note: this information is not always meaningful for all outputs. Some
3031+ compositors, such as those exposing virtual outputs, might fake the
3032+ refresh rate or the size.
3033+ </description>
3034+ <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
3035+ <arg name="width" type="int" summary="width of the mode in hardware units"/>
3036+ <arg name="height" type="int" summary="height of the mode in hardware units"/>
3037+ <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
3038+ </event>
3039+
3040+ <!-- Version 2 additions -->
3041+
3042+ <event name="done" since="2">
3043+ <description summary="sent all information about output">
3044+ This event is sent after all other properties have been
3045+ sent after binding to the output object and after any
3046+ other property changes done after that. This allows
3047+ changes to the output properties to be seen as
3048+ atomic, even if they happen via multiple events.
3049+ </description>
3050+ </event>
3051+
3052+ <event name="scale" since="2">
3053+ <description summary="output scaling properties">
3054+ This event contains scaling geometry information
3055+ that is not in the geometry event. It may be sent after
3056+ binding the output object or if the output scale changes
3057+ later. The compositor will emit a non-zero, positive
3058+ value for scale. If it is not sent, the client should
3059+ assume a scale of 1.
3060+
3061+ A scale larger than 1 means that the compositor will
3062+ automatically scale surface buffers by this amount
3063+ when rendering. This is used for very high resolution
3064+ displays where applications rendering at the native
3065+ resolution would be too small to be legible.
3066+
3067+ Clients should use wl_surface.preferred_buffer_scale
3068+ instead of this event to find the preferred buffer
3069+ scale to use for a surface.
3070+
3071+ The scale event will be followed by a done event.
3072+ </description>
3073+ <arg name="factor" type="int" summary="scaling factor of output"/>
3074+ </event>
3075+
3076+ <!-- Version 3 additions -->
3077+
3078+ <request name="release" type="destructor" since="3">
3079+ <description summary="release the output object">
3080+ Using this request a client can tell the server that it is not going to
3081+ use the output object anymore.
3082+ </description>
3083+ </request>
3084+
3085+ <!-- Version 4 additions -->
3086+
3087+ <event name="name" since="4">
3088+ <description summary="name of this output">
3089+ Many compositors will assign user-friendly names to their outputs, show
3090+ them to the user, allow the user to refer to an output, etc. The client
3091+ may wish to know this name as well to offer the user similar behaviors.
3092+
3093+ The name is a UTF-8 string with no convention defined for its contents.
3094+ Each name is unique among all wl_output globals. The name is only
3095+ guaranteed to be unique for the compositor instance.
3096+
3097+ The same output name is used for all clients for a given wl_output
3098+ global. Thus, the name can be shared across processes to refer to a
3099+ specific wl_output global.
3100+
3101+ The name is not guaranteed to be persistent across sessions, thus cannot
3102+ be used to reliably identify an output in e.g. configuration files.
3103+
3104+ Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
3105+ not assume that the name is a reflection of an underlying DRM connector,
3106+ X11 connection, etc.
3107+
3108+ The name event is sent after binding the output object. This event is
3109+ only sent once per output object, and the name does not change over the
3110+ lifetime of the wl_output global.
3111+
3112+ Compositors may re-use the same output name if the wl_output global is
3113+ destroyed and re-created later. Compositors should avoid re-using the
3114+ same name if possible.
3115+
3116+ The name event will be followed by a done event.
3117+ </description>
3118+ <arg name="name" type="string" summary="output name"/>
3119+ </event>
3120+
3121+ <event name="description" since="4">
3122+ <description summary="human-readable description of this output">
3123+ Many compositors can produce human-readable descriptions of their
3124+ outputs. The client may wish to know this description as well, e.g. for
3125+ output selection purposes.
3126+
3127+ The description is a UTF-8 string with no convention defined for its
3128+ contents. The description is not guaranteed to be unique among all
3129+ wl_output globals. Examples might include 'Foocorp 11" Display' or
3130+ 'Virtual X11 output via :1'.
3131+
3132+ The description event is sent after binding the output object and
3133+ whenever the description changes. The description is optional, and may
3134+ not be sent at all.
3135+
3136+ The description event will be followed by a done event.
3137+ </description>
3138+ <arg name="description" type="string" summary="output description"/>
3139+ </event>
3140+ </interface>
3141+
3142+ <interface name="wl_region" version="7">
3143+ <description summary="region interface">
3144+ A region object describes an area.
3145+
3146+ Region objects are used to describe the opaque and input
3147+ regions of a surface.
3148+ </description>
3149+
3150+ <request name="destroy" type="destructor">
3151+ <description summary="destroy region">
3152+ Destroy the region. This will invalidate the object ID.
3153+ </description>
3154+ </request>
3155+
3156+ <request name="add">
3157+ <description summary="add rectangle to region">
3158+ Add the specified rectangle to the region.
3159+ </description>
3160+ <arg name="x" type="int" summary="region-local x coordinate"/>
3161+ <arg name="y" type="int" summary="region-local y coordinate"/>
3162+ <arg name="width" type="int" summary="rectangle width"/>
3163+ <arg name="height" type="int" summary="rectangle height"/>
3164+ </request>
3165+
3166+ <request name="subtract">
3167+ <description summary="subtract rectangle from region">
3168+ Subtract the specified rectangle from the region.
3169+ </description>
3170+ <arg name="x" type="int" summary="region-local x coordinate"/>
3171+ <arg name="y" type="int" summary="region-local y coordinate"/>
3172+ <arg name="width" type="int" summary="rectangle width"/>
3173+ <arg name="height" type="int" summary="rectangle height"/>
3174+ </request>
3175+ </interface>
3176+
3177+ <interface name="wl_subcompositor" version="1">
3178+ <description summary="sub-surface compositing">
3179+ The global interface exposing sub-surface compositing capabilities.
3180+ A wl_surface, that has sub-surfaces associated, is called the
3181+ parent surface. Sub-surfaces can be arbitrarily nested and create
3182+ a tree of sub-surfaces.
3183+
3184+ The root surface in a tree of sub-surfaces is the main
3185+ surface. The main surface cannot be a sub-surface, because
3186+ sub-surfaces must always have a parent.
3187+
3188+ A main surface with its sub-surfaces forms a (compound) window.
3189+ For window management purposes, this set of wl_surface objects is
3190+ to be considered as a single window, and it should also behave as
3191+ such.
3192+
3193+ The aim of sub-surfaces is to offload some of the compositing work
3194+ within a window from clients to the compositor. A prime example is
3195+ a video player with decorations and video in separate wl_surface
3196+ objects. This should allow the compositor to pass YUV video buffer
3197+ processing to dedicated overlay hardware when possible.
3198+ </description>
3199+
3200+ <request name="destroy" type="destructor">
3201+ <description summary="unbind from the subcompositor interface">
3202+ Informs the server that the client will not be using this
3203+ protocol object anymore. This does not affect any other
3204+ objects, wl_subsurface objects included.
3205+ </description>
3206+ </request>
3207+
3208+ <enum name="error">
3209+ <entry name="bad_surface" value="0"
3210+ summary="the to-be sub-surface is invalid"/>
3211+ <entry name="bad_parent" value="1"
3212+ summary="the to-be sub-surface parent is invalid"/>
3213+ </enum>
3214+
3215+ <request name="get_subsurface">
3216+ <description summary="give a surface the role sub-surface">
3217+ Create a sub-surface interface for the given surface, and
3218+ associate it with the given parent surface. This turns a
3219+ plain wl_surface into a sub-surface.
3220+
3221+ The to-be sub-surface must not already have another role, and it
3222+ must not have an existing wl_subsurface object. Otherwise the
3223+ bad_surface protocol error is raised.
3224+
3225+ Adding sub-surfaces to a parent is a double-buffered operation on the
3226+ parent (see wl_surface.commit). The effect of adding a sub-surface
3227+ becomes visible on the next time the state of the parent surface is
3228+ applied.
3229+
3230+ The parent surface must not be one of the child surface's descendants,
3231+ and the parent must be different from the child surface, otherwise the
3232+ bad_parent protocol error is raised.
3233+
3234+ This request modifies the behaviour of wl_surface.commit request on
3235+ the sub-surface, see the documentation on wl_subsurface interface.
3236+ </description>
3237+ <arg name="id" type="new_id" interface="wl_subsurface"
3238+ summary="the new sub-surface object ID"/>
3239+ <arg name="surface" type="object" interface="wl_surface"
3240+ summary="the surface to be turned into a sub-surface"/>
3241+ <arg name="parent" type="object" interface="wl_surface"
3242+ summary="the parent surface"/>
3243+ </request>
3244+ </interface>
3245+
3246+ <interface name="wl_subsurface" version="1">
3247+ <description summary="sub-surface interface to a wl_surface">
3248+ An additional interface to a wl_surface object, which has been
3249+ made a sub-surface. A sub-surface has one parent surface. A
3250+ sub-surface's size and position are not limited to that of the parent.
3251+ Particularly, a sub-surface is not automatically clipped to its
3252+ parent's area.
3253+
3254+ A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
3255+ and the parent surface is mapped. The order of which one happens
3256+ first is irrelevant. A sub-surface is hidden if the parent becomes
3257+ hidden, or if a NULL wl_buffer is applied. These rules apply
3258+ recursively through the tree of surfaces.
3259+
3260+ A sub-surface can be in one of two modes. The possible modes are
3261+ synchronized and desynchronized, see methods wl_subsurface.set_sync and
3262+ wl_subsurface.set_desync.
3263+
3264+ The main surface can be thought to be always in desynchronized mode,
3265+ since it does not have a parent in the sub-surfaces sense.
3266+
3267+ Even if a sub-surface is in desynchronized mode, it will behave as
3268+ in synchronized mode, if its parent surface behaves as in
3269+ synchronized mode. This rule is applied recursively throughout the
3270+ tree of surfaces. This means, that one can set a sub-surface into
3271+ synchronized mode, and then assume that all its child and grand-child
3272+ sub-surfaces are synchronized, too, without explicitly setting them.
3273+
3274+ If a surface behaves as in synchronized mode, it is effectively
3275+ synchronized, otherwise it is effectively desynchronized.
3276+
3277+ A sub-surface is initially in the synchronized mode.
3278+
3279+ The wl_subsurface interface has requests which modify double-buffered
3280+ state of the parent surface (wl_subsurface.set_position, .place_above and
3281+ .place_below).
3282+
3283+ Destroying a sub-surface takes effect immediately. If you need to
3284+ synchronize the removal of a sub-surface to the parent surface update,
3285+ unmap the sub-surface first by attaching a NULL wl_buffer, update parent,
3286+ and then destroy the sub-surface.
3287+
3288+ If the parent wl_surface object is destroyed, the sub-surface is
3289+ unmapped.
3290+
3291+ A sub-surface never has the keyboard focus of any seat.
3292+
3293+ The wl_surface.offset request is ignored: clients must use set_position
3294+ instead to move the sub-surface.
3295+ </description>
3296+
3297+ <request name="destroy" type="destructor">
3298+ <description summary="remove sub-surface interface">
3299+ The sub-surface interface is removed from the wl_surface object
3300+ that was turned into a sub-surface with a
3301+ wl_subcompositor.get_subsurface request. The wl_surface's association
3302+ to the parent is deleted. The wl_surface is unmapped immediately.
3303+ </description>
3304+ </request>
3305+
3306+ <enum name="error">
3307+ <entry name="bad_surface" value="0"
3308+ summary="wl_surface is not a sibling or the parent"/>
3309+ </enum>
3310+
3311+ <request name="set_position">
3312+ <description summary="reposition the sub-surface">
3313+ This sets the position of the sub-surface, relative to the parent
3314+ surface.
3315+
3316+ The sub-surface will be moved so that its origin (top left
3317+ corner pixel) will be at the location x, y of the parent surface
3318+ coordinate system. The coordinates are not restricted to the parent
3319+ surface area. Negative values are allowed.
3320+
3321+ The initial position is 0, 0.
3322+
3323+ Position is double-buffered state on the parent surface, see
3324+ wl_subsurface and wl_surface.commit for more information.
3325+ </description>
3326+ <arg name="x" type="int" summary="x coordinate in the parent surface"/>
3327+ <arg name="y" type="int" summary="y coordinate in the parent surface"/>
3328+ </request>
3329+
3330+ <request name="place_above">
3331+ <description summary="restack the sub-surface">
3332+ This sub-surface is taken from the stack, and put back just
3333+ above the reference surface, changing the z-order of the sub-surfaces.
3334+ The reference surface must be one of the sibling surfaces, or the
3335+ parent surface. Using any other surface, including this sub-surface,
3336+ will cause a protocol error.
3337+
3338+ A new sub-surface is initially added as the top-most in the stack
3339+ of its siblings and parent.
3340+
3341+ Z-order is double-buffered state on the parent surface, see
3342+ wl_subsurface and wl_surface.commit for more information.
3343+ </description>
3344+ <arg name="sibling" type="object" interface="wl_surface"
3345+ summary="the reference surface"/>
3346+ </request>
3347+
3348+ <request name="place_below">
3349+ <description summary="restack the sub-surface">
3350+ The sub-surface is placed just below the reference surface.
3351+
3352+ See wl_subsurface.place_above.
3353+ </description>
3354+ <arg name="sibling" type="object" interface="wl_surface"
3355+ summary="the reference surface"/>
3356+ </request>
3357+
3358+ <request name="set_sync">
3359+ <description summary="set sub-surface to synchronized mode">
3360+ Change the commit behaviour of the sub-surface to synchronized
3361+ mode.
3362+
3363+ See wl_subsurface and wl_surface.commit for more information.
3364+ </description>
3365+ </request>
3366+
3367+ <request name="set_desync">
3368+ <description summary="set sub-surface to desynchronized mode">
3369+ Change the commit behaviour of the sub-surface to desynchronized
3370+ mode.
3371+
3372+ See wl_subsurface and wl_surface.commit for more information.
3373+ </description>
3374+ </request>
3375+ </interface>
3376+
3377+ <interface name="wl_fixes" version="2">
3378+ <description summary="wayland protocol fixes">
3379+ This global fixes problems with other core-protocol interfaces that
3380+ cannot be fixed in these interfaces themselves.
3381+ </description>
3382+
3383+ <enum name="error">
3384+ <description summary="wl_fixes error values">
3385+ These errors can be emitted in response to wl_fixes requests.
3386+ </description>
3387+ <entry name="invalid_ack_remove" value="0"
3388+ summary="unknown global or the global is not removed"/>
3389+ </enum>
3390+
3391+ <request name="destroy" type="destructor">
3392+ <description summary="destroys this object"/>
3393+ </request>
3394+
3395+ <request name="destroy_registry">
3396+ <description summary="destroy a wl_registry">
3397+ This request destroys a wl_registry object.
3398+
3399+ The client should no longer use the wl_registry after making this
3400+ request.
3401+
3402+ The compositor will emit a wl_display.delete_id event with the object ID
3403+ of the registry and will no longer emit any events on the registry. The
3404+ client should re-use the object ID once it receives the
3405+ wl_display.delete_id event.
3406+ </description>
3407+ <arg name="registry" type="object" interface="wl_registry"
3408+ summary="the registry to destroy"/>
3409+ </request>
3410+
3411+ <request name="ack_global_remove" since="2">
3412+ <description summary="acknowledge global removal">
3413+ Acknowledge the removal of the specified global.
3414+
3415+ If no global with the specified name exists or the global is not removed,
3416+ the wl_fixes.invalid_ack_remove protocol error will be posted.
3417+
3418+ Due to the Wayland protocol being asynchronous, the wl_global objects
3419+ cannot be destroyed immediately. For example, if a wl_global is removed
3420+ and a client attempts to bind that global around same time, it can
3421+ result in a protocol error due to an unknown global name in the bind
3422+ request.
3423+
3424+ In order to avoid crashing clients, the compositor should remove the
3425+ wl_global once it is guaranteed that no more bind requests will come.
3426+
3427+ The wl_fixes.ack_global_remove() request is used to signal to the
3428+ compositor that the client will not bind the given global anymore. After
3429+ all clients acknowledge the removal of the global, the compositor can
3430+ safely destroy it.
3431+
3432+ The client must call the wl_fixes.ack_global_remove() request in
3433+ response to a wl_registry.global_remove() event even if it did not bind
3434+ the corresponding global.
3435+ </description>
3436+ <arg name="registry" type="object" interface="wl_registry"
3437+ summary="the registry object"/>
3438+ <arg name="name" type="uint" summary="unique name of the global"/>
3439+ </request>
3440+ </interface>
3441+
3442+</protocol>

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 8

↑↓ moveenter openesc close