doc.go (2582B)
1 // Copyright 2014 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package gl implements Go bindings for OpenGL ES 2.0 and ES 3.0. 7 8 The GL functions are defined on a Context object that is responsible for 9 tracking a GL context. Typically a windowing system package (such as 10 golang.org/x/exp/shiny/screen) will call NewContext and provide 11 a gl.Context for a user application. 12 13 If the gl package is compiled on a platform capable of supporting ES 3.0, 14 the gl.Context object also implements gl.Context3. 15 16 The bindings are deliberately minimal, staying as close the C API as 17 possible. The semantics of each function maps onto functions 18 described in the Khronos documentation: 19 20 https://www.khronos.org/opengles/sdk/docs/man/ 21 22 One notable departure from the C API is the introduction of types 23 to represent common uses of GLint: Texture, Surface, Buffer, etc. 24 25 Debug Logging 26 27 A tracing version of the OpenGL bindings is behind the `gldebug` build 28 tag. It acts as a simplified version of apitrace. Build your Go binary 29 with 30 31 -tags gldebug 32 33 and each call to a GL function will log its input, output, and any 34 error messages. For example, 35 36 I/GoLog (27668): gl.GenBuffers(1) [Buffer(70001)] 37 I/GoLog (27668): gl.BindBuffer(ARRAY_BUFFER, Buffer(70001)) 38 I/GoLog (27668): gl.BufferData(ARRAY_BUFFER, 36, len(36), STATIC_DRAW) 39 I/GoLog (27668): gl.BindBuffer(ARRAY_BUFFER, Buffer(70001)) 40 I/GoLog (27668): gl.VertexAttribPointer(Attrib(0), 6, FLOAT, false, 0, 0) error: [INVALID_VALUE] 41 42 The gldebug tracing has very high overhead, so make sure to remove 43 the build tag before deploying any binaries. 44 */ 45 package gl // import "golang.org/x/mobile/gl" 46 47 /* 48 Implementation details. 49 50 All GL function calls fill out a C.struct_fnargs and drop it on the work 51 queue. The Start function drains the work queue and hands over a batch 52 of calls to C.process which runs them. This allows multiple GL calls to 53 be executed in a single cgo call. 54 55 A GL call is marked as blocking if it returns a value, or if it takes a 56 Go pointer. In this case the call will not return until C.process sends a 57 value on the retvalue channel. 58 59 This implementation ensures any goroutine can make GL calls, but it does 60 not make the GL interface safe for simultaneous use by multiple goroutines. 61 For the purpose of analyzing this code for race conditions, picture two 62 separate goroutines: one blocked on gl.Start, and another making calls to 63 the gl package exported functions. 64 */ 65 66 //go:generate go run gendebug.go -o gldebug.go