zorldo

Goofing around with Ebiten
git clone git://bsandro.tech/zorldo
Log | Files | Refs | README

doc.go (4605B)

      1 /*
      2 Package XGB provides the X Go Binding, which is a low-level API to communicate
      3 with the core X protocol and many of the X extensions.
      4 
      5 It is *very* closely modeled on XCB, so that experience with XCB (or xpyb) is
      6 easily translatable to XGB. That is, it uses the same cookie/reply model
      7 and is thread safe. There are otherwise no major differences (in the API).
      8 
      9 Most uses of XGB typically fall under the realm of window manager and GUI kit
     10 development, but other applications (like pagers, panels, tilers, etc.) may
     11 also require XGB. Moreover, it is a near certainty that if you need to work
     12 with X, xgbutil will be of great use to you as well:
     13 https://github.com/jezek/xgbutil
     14 
     15 Example
     16 
     17 This is an extremely terse example that demonstrates how to connect to X,
     18 create a window, listen to StructureNotify events and Key{Press,Release}
     19 events, map the window, and print out all events received. An example with
     20 accompanying documentation can be found in examples/create-window.
     21 
     22 	package main
     23 
     24 	import (
     25 		"fmt"
     26 		"github.com/jezek/xgb"
     27 		"github.com/jezek/xgb/xproto"
     28 	)
     29 
     30 	func main() {
     31 		X, err := xgb.NewConn()
     32 		if err != nil {
     33 			fmt.Println(err)
     34 			return
     35 		}
     36 
     37 		wid, _ := xproto.NewWindowId(X)
     38 		screen := xproto.Setup(X).DefaultScreen(X)
     39 		xproto.CreateWindow(X, screen.RootDepth, wid, screen.Root,
     40 			0, 0, 500, 500, 0,
     41 			xproto.WindowClassInputOutput, screen.RootVisual,
     42 			xproto.CwBackPixel | xproto.CwEventMask,
     43 			[]uint32{ // values must be in the order defined by the protocol
     44 				0xffffffff,
     45 				xproto.EventMaskStructureNotify |
     46 				xproto.EventMaskKeyPress |
     47 				xproto.EventMaskKeyRelease})
     48 
     49 		xproto.MapWindow(X, wid)
     50 		for {
     51 			ev, xerr := X.WaitForEvent()
     52 			if ev == nil && xerr == nil {
     53 				fmt.Println("Both event and error are nil. Exiting...")
     54 				return
     55 			}
     56 
     57 			if ev != nil {
     58 				fmt.Printf("Event: %s\n", ev)
     59 			}
     60 			if xerr != nil {
     61 				fmt.Printf("Error: %s\n", xerr)
     62 			}
     63 		}
     64 	}
     65 
     66 Xinerama Example
     67 
     68 This is another small example that shows how to query Xinerama for geometry
     69 information of each active head. Accompanying documentation for this example
     70 can be found in examples/xinerama.
     71 
     72 	package main
     73 
     74 	import (
     75 		"fmt"
     76 		"log"
     77 		"github.com/jezek/xgb"
     78 		"github.com/jezek/xgb/xinerama"
     79 	)
     80 
     81 	func main() {
     82 		X, err := xgb.NewConn()
     83 		if err != nil {
     84 			log.Fatal(err)
     85 		}
     86 
     87 		// Initialize the Xinerama extension.
     88 		// The appropriate 'Init' function must be run for *every*
     89 		// extension before any of its requests can be used.
     90 		err = xinerama.Init(X)
     91 		if err != nil {
     92 			log.Fatal(err)
     93 		}
     94 
     95 		reply, err := xinerama.QueryScreens(X).Reply()
     96 		if err != nil {
     97 			log.Fatal(err)
     98 		}
     99 
    100 		fmt.Printf("Number of heads: %d\n", reply.Number)
    101 		for i, screen := range reply.ScreenInfo {
    102 			fmt.Printf("%d :: X: %d, Y: %d, Width: %d, Height: %d\n",
    103 				i, screen.XOrg, screen.YOrg, screen.Width, screen.Height)
    104 		}
    105 	}
    106 
    107 Parallelism
    108 
    109 XGB can benefit greatly from parallelism due to its concurrent design. For
    110 evidence of this claim, please see the benchmarks in xproto/xproto_test.go.
    111 
    112 Tests
    113 
    114 xproto/xproto_test.go contains a number of contrived tests that stress
    115 particular corners of XGB that I presume could be problem areas. Namely:
    116 requests with no replies, requests with replies, checked errors, unchecked
    117 errors, sequence number wrapping, cookie buffer flushing (i.e., forcing a round
    118 trip every N requests made that don't have a reply), getting/setting properties
    119 and creating a window and listening to StructureNotify events.
    120 
    121 Code Generator
    122 
    123 Both XCB and xpyb use the same Python module (xcbgen) for a code generator. XGB
    124 (before this fork) used the same code generator as well, but in my attempt to
    125 add support for more extensions, I found the code generator extremely difficult
    126 to work with. Therefore, I re-wrote the code generator in Go. It can be found
    127 in its own sub-package, xgbgen, of xgb. My design of xgbgen includes a rough
    128 consideration that it could be used for other languages.
    129 
    130 What works
    131 
    132 I am reasonably confident that the core X protocol is in full working form. I've
    133 also tested the Xinerama and RandR extensions sparingly. Many of the other
    134 existing extensions have Go source generated (and are compilable) and are
    135 included in this package, but I am currently unsure of their status. They
    136 *should* work.
    137 
    138 What does not work
    139 
    140 XKB is the only extension that intentionally does not work, although I suspect
    141 that GLX also does not work (however, there is Go source code for GLX that
    142 compiles, unlike XKB). I don't currently have any intention of getting XKB
    143 working, due to its complexity and my current mental incapacity to test it.
    144 
    145 */
    146 package xgb