github.com/acrespo/mobile@v0.0.0-20190107162257-dc0771356504/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.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