github.com/graybobo/golang.org-package-offline-cache@v0.0.0-20200626051047-6608995c132f/x/mobile/gl/doc.go (about)

     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.
     7  
     8  The bindings are deliberately minimal, staying as close the C API as
     9  possible. The semantics of each function maps onto functions
    10  described in the Khronos documentation:
    11  
    12  https://www.khronos.org/opengles/sdk/docs/man/
    13  
    14  One notable departure from the C API is the introduction of types
    15  to represent common uses of GLint: Texture, Surface, Buffer, etc.
    16  
    17  Debug Logging
    18  
    19  A tracing version of the OpenGL bindings is behind the `gldebug` build
    20  tag. It acts as a simplified version of apitrace. Build your Go binary
    21  with
    22  
    23  	-tags gldebug
    24  
    25  and each call to a GL function will log its input, output, and any
    26  error messages. For example,
    27  
    28  	I/GoLog   (27668): gl.GenBuffers(1) [Buffer(70001)]
    29  	I/GoLog   (27668): gl.BindBuffer(ARRAY_BUFFER, Buffer(70001))
    30  	I/GoLog   (27668): gl.BufferData(ARRAY_BUFFER, 36, len(36), STATIC_DRAW)
    31  	I/GoLog   (27668): gl.BindBuffer(ARRAY_BUFFER, Buffer(70001))
    32  	I/GoLog   (27668): gl.VertexAttribPointer(Attrib(0), 6, FLOAT, false, 0, 0)  error: [INVALID_VALUE]
    33  
    34  The gldebug tracing has very high overhead, so make sure to remove
    35  the build tag before deploying any binaries.
    36  */
    37  package gl // import "golang.org/x/mobile/gl"
    38  
    39  /*
    40  Implementation details.
    41  
    42  All GL function calls fill out a C.struct_fnargs and drop it on the work
    43  queue. The Start function drains the work queue and hands over a batch
    44  of calls to C.process which runs them. This allows multiple GL calls to
    45  be executed in a single cgo call.
    46  
    47  A GL call is marked as blocking if it returns a value, or if it takes a
    48  Go pointer. In this case the call will not return until C.process sends a
    49  value on the retvalue channel.
    50  
    51  This implementation ensures any goroutine can make GL calls, but it does
    52  not make the GL interface safe for simultaneous use by multiple goroutines.
    53  For the purpose of analyzing this code for race conditions, picture two
    54  separate goroutines: one blocked on gl.Start, and another making calls to
    55  the gl package exported functions.
    56  */
    57  
    58  //go:generate go run gendebug.go -o gldebug.go