gigl

README

GIGL : Interactive 2D & 3D Graphics Library in Go

GIGL implements full set of high-level constructs of interactive 2D & 3D graphics (such as Camera, Scene, Geometry, Material, Overlay, etc.) entirely in Go, so that they can be easily used in any OpenGL/WebGL environments on native applications or webapps in a browser.

This project is under development, and backward-incompatible changes can be made.

How to Build & Run

Simplest example:   (for explaining how WebGL/OpenGL works)

$ make webgl_1st        # source : 'tutorial/webgl_1st/webgl_1st.go'
$ make webgl_run
or
$ make opengl_1st       # source : 'tutorial/opengl_1st/opengl_1st.go'

2D example:   (for basic 2D usage with Geometry)

$ make webgl_2d         # source : 'tutorial/webgl_2d/webgl_2d.go'
$ make webgl_run
or
$ make opengl_2d        # source : 'tutorial/opengl_2d/opengl_2d.go'

2Di example:   (with Geometry Instaces, Labels & Markers)

$ make webgl_2di        # source : 'tutorial/webgl_2di/webgl_2di.go'
$ make webgl_run

3D example:   (basic 3D usage with Geometry, Texture and Camera)

$ make webgl_3d        # source : 'tutorial/webgl_3d/webgl_3d.go'
$ make webgl_run
or
$ make opengl_3d       # source : 'tutorial/opengl_3d/opengl_3d.go'

Spinnig Globe example:   (with a specialized sphere geometry, glow effect, and user interactions)

$ make webgl_globe    # source : 'tutorial/webgl_globe/webgl_globe.go'
$ make webgl_run

ToDo List

• examples for other OpenGL environment on native applications
• overlay (marker/label) layers for Globe
• user selection using collision detection with a ray from camera
• graticules on the globe
• coast lines and country border lines on the world map
• support for world map projections (Mercator, Stereographic, etc)

Notes on OpenGL Environments

Supporting different OpenGL environments is not a trivial task, and it always have been a headache for a starter. We really want to make it as easy as possible for Go programmers. For a webapp in a browser, we use the experimental Go support (syscall/js) for WebAssembly. For a native app, we use go-gl's libraries such as gl & glfw. In order to deal with different versions of GLSL (OpenGL Shading Language), we have written all the shader codes in WebGL 1.0 (#version 100 es) as the default GLSL version, and convert the shader codes automatically into OpenGL 4.1 (#version 410) for OpenGL environments. Note that OpenGL 4.1 and OpenGL ES 2.0 and WebGL 1.0 are mostly compatible with each other.

Thanks

I hope this project can help many people to learn 2D & 3D graphics and to build awesome applications in Go.
Special thanks to the members of go-gl group and Richard Musiol, for their visions and so many contributions.
If you hava a feedback or suggestion, contact go4orward.

Resources taken from:

• Go Gopher images : originally created by Renee French
• VisibleEarth by NASA : world satellite images
• NaturalEarth : public domain map dataset

Documentation

Index

• type BindTarget
  • func (self *BindTarget) String() string
• type GLConstants
• type GLGeometry
• type GLMaterial
• type GLMaterialColors
• type GLMaterialTexture
• type GLRenderingContext
• type GLShader
• type GLShaderBinder
  • func (self *GLShaderBinder) GetAttributeBindings() map[string]BindTarget
  • func (self *GLShaderBinder) GetUniformBindings() map[string]BindTarget
  • func (self *GLShaderBinder) InitBindings()
  • func (self *GLShaderBinder) SetBindingForAttribute(btype cst.BindType, name string, target any)
  • func (self *GLShaderBinder) SetBindingForUniform(btype cst.BindType, name string, target any)
• type VAO
  • func (self *VAO) GetIdxBuffer(draw_mode int) (interface{}, int)
  • func (self *VAO) GetInstanceBuffer() (interface{}, [2]int)
  • func (self *VAO) GetVtxBuffer(draw_mode int, xun int) (interface{}, [4]int)
  • func (self *VAO) ShowInfo()

Types

type BindTarget

type BindTarget struct {
	Type   cst.BindType // data type      of the variable
	Loc    any          // location       of the variable
	Target any          // target (value) of the variable
}

func (*BindTarget) String

func (self *BindTarget) String() string

type GLConstants

type GLConstants struct {
	ARRAY_BUFFER         uint32 //
	BLEND                uint32 // for gl.enable(gl.BLEND)
	BYTE                 uint32 //
	CLAMP_TO_EDGE        uint32 // for gl.texParameteri()
	COLOR_BUFFER_BIT     uint32 //
	COMPILE_STATUS       uint32 //
	DEPTH_BUFFER_BIT     uint32 //
	DEPTH_TEST           uint32 //
	ELEMENT_ARRAY_BUFFER uint32 //
	FLOAT                uint32 //
	FRAGMENT_SHADER      uint32 //
	LEQUAL               uint32 //
	LESS                 uint32 //
	LINEAR               uint32 // for gl.texParameteri()
	LINES                uint32 //
	LINK_STATUS          uint32 //
	NEAREST              uint32 // for gl.texParameteri()
	ONE                  uint32 // for gl.blendFunc()
	ONE_MINUS_SRC_ALPHA  uint32 // for gl.blendFunc()
	POINTS               uint32 //
	RGBA                 uint32 //
	SRC_ALPHA            uint32 // for gl.blendFunc()
	STATIC_DRAW          uint32 //
	TEXTURE_2D           uint32 // for gl.texParameteri()
	TEXTURE0             uint32 //
	TEXTURE1             uint32 //
	TEXTURE_MIN_FILTER   uint32 // for gl.texParameteri()
	TEXTURE_WRAP_S       uint32 // for gl.texParameteri()
	TEXTURE_WRAP_T       uint32 // for gl.texParameteri()
	TRIANGLES            uint32 //
	UNSIGNED_BYTE        uint32 //
	UNSIGNED_INT         uint32 //
	UNSIGNED_SHORT       uint32 //
	VERTEX_SHADER        uint32 //
}

type GLGeometry

type GLGeometry interface {
	// This interface defines a set of functions that both 2D and 3D Geometry have to provide.
	// NewSceneObject() function requires this GLGeometry interface instead of a 2D or 3D Geometry,
	// since 3D SceneObject should be able to use both 2D and 3D Geometry (as in g3d.OverlayMarkerLayer).
	IsDataBufferReady() bool
	IsVtxBufferRebuiltForFaces() bool
	GetVtxBuffer(draw_mode int) []float32  // data buffer of vertices (mode 0:original_verts, 1:face_verts_only)
	GetIdxBuffer(draw_mode int) []uint32   // data buffer of indices  (mode 2:for_edges, 3:for_faces)
	GetVtxBufferInfo(draw_mode int) [5]int // data buffer info : [nverts, stride, xyz_size, uv_size, normal_size]
	GetIdxBufferCount(draw_mode int) int   // data buffer count : number of vertex indices
	Summary() string                       //
}

type GLMaterial

type GLMaterial interface {
	MaterialSummary() string
}

type GLMaterialColors

type GLMaterialColors interface {
	MaterialSummary() string

	GetDrawModeColor(draw_mode int) [4]float32
}

type GLMaterialTexture

type GLMaterialTexture interface {
	MaterialSummary() string

	GetTexturePixbuf() []uint8
	GetTextureWH() [2]int

	GetTexture() any
	SetTexture(texture any)
	GetTextureRGB() [3]float32
	SetTextureRGB(color any)

	IsLoading() bool // Texture is being loaded asynchronously by non-main thread (using Go function).
	IsLoaded() bool  // Texture was successfully loaded, and it needs to be set up by main thread.
	IsReady() bool   // Texture was successfully set up, and it's ready for rendering.
}

type GLRenderingContext

type GLRenderingContext interface {
	GetWH() [2]int
	GetConstants() *GLConstants
	GetEnvVariable(vname string, dtype string) interface{}

	// Material
	LoadMaterial(material GLMaterial) error
	SetupMaterial(material GLMaterial) error

	// Shader
	CreateShader(vertex_shader string, fragment_shader string) (GLShader, error)
	// DataBuffer
	CreateDataBufferVAO() *VAO
	CreateVtxDataBuffer(data_slice []float32) interface{}
	CreateIdxDataBuffer(data_slice []uint32) interface{}

	// Binding DataBuffer
	GLBindBuffer(binding_target uint32, buffer interface{})

	// Binding Texture
	GLActiveTexture(texture_unit int)
	GLBindTexture(target uint32, texture interface{})

	// Binding Uniforms
	GLUniform1i(location interface{}, v0 int)
	GLUniform1f(location interface{}, v0 float32)
	GLUniform2f(location interface{}, v0 float32, v1 float32)
	GLUniform3f(location interface{}, v0 float32, v1 float32, v2 float32)
	GLUniform4f(location interface{}, v0 float32, v1 float32, v2 float32, v3 float32)
	GLUniformMatrix3fv(location interface{}, transpose bool, values []float32)
	GLUniformMatrix4fv(location interface{}, transpose bool, values []float32)

	// Binding Attributes
	GLVertexAttribPointer(location interface{}, size int, dtype uint32, normalized bool, stride_in_byte int, offset_in_byte int)
	GLEnableVertexAttribArray(location interface{})
	GLVertexAttribDivisor(location interface{}, divisor int)

	// Preparing to Render
	GLClearColor(r float32, g float32, b float32, a float32)
	GLClear(mask uint32)
	GLEnable(cap uint32)
	GLDisable(cap uint32)
	GLDepthFunc(ftn uint32)
	GLBlendFunc(sfactor uint32, dfactor uint32)
	GLUseProgram(program interface{})

	// Rendering
	GLDrawArrays(mode uint32, first int, count int)
	GLDrawArraysInstanced(mode uint32, first int, count int, pose_count int)
	GLDrawElements(mode uint32, count int, dtype uint32, offset int)
	GLDrawElementsInstanced(mode uint32, element_count int, dtype uint32, offset int, pose_count int)

	// WebGL Extensions
	SetupExtension(extname string)
	IsExtensionReady(extname string) bool
}

type GLShader

type GLShader interface {
	// Note that the creator NewShader() function should be implemented
	//   for each environment (like NewWebGLShader()/NewOpenGLShader()).
	CreateShaderProgram(vshader_source string, fshader_source string)
	GetShaderProgram() any
	IsReady() bool
	GetErr() error // returns any error during the creator function

	// setting up shader bindings
	SetBindingForUniform(btype cst.BindType, name string, target any)
	SetBindingForAttribute(btype cst.BindType, name string, target any)
	CheckBindings()
	GetUniformBindings() map[string]BindTarget
	GetAttributeBindings() map[string]BindTarget

	//
	Copy() GLShader
	String() string
	Summary() string
}

type GLShaderBinder

type GLShaderBinder struct {
	Uniforms   map[string]BindTarget // shader uniforms to bind
	Attributes map[string]BindTarget // shader attributes to bind
}

func (*GLShaderBinder) GetAttributeBindings

func (self *GLShaderBinder) GetAttributeBindings() map[string]BindTarget

func (*GLShaderBinder) GetUniformBindings

func (self *GLShaderBinder) GetUniformBindings() map[string]BindTarget

func (*GLShaderBinder) InitBindings

func (self *GLShaderBinder) InitBindings()

func (*GLShaderBinder) SetBindingForAttribute

func (self *GLShaderBinder) SetBindingForAttribute(btype cst.BindType, name string, target any)

func (*GLShaderBinder) SetBindingForUniform

func (self *GLShaderBinder) SetBindingForUniform(btype cst.BindType, name string, target any)

type VAO

type VAO struct {
	VertBuffer     interface{} // WebGL/OpenGL buffer for geometry's vertex points
	FvtxBuffer     interface{} // WebGL/OpenGL buffer for geometry's face vertex points (points for PER_FACE vertices)
	VertBufferInfo [5]int      // [nverts, stride, coord_size, texture_uv_size, vertex_normal_size]
	FvtxBufferInfo [5]int      // [nverts, stride, coord_size, texture_uv_size, vertex_normal_size]

	EdgeBuffer      interface{} // WebGL/OpenGL buffer for geometry's edge indices
	FaceBuffer      interface{} // WebGL/OpenGL buffer for geometry's face indices
	EdgeBufferCount int         // EdgeBuffer count (number of uint32 vertex indices)
	FaceBufferCount int         // EdgeBuffer count (number of uint32 vertex indices)

	InstanceBuffer     interface{} // WebGL/OpenGL buffer for geometry's instance values
	InstanceBufferInfo [2]int      // [instance_count, instance_stride] of instance poses
}

func (*VAO) GetIdxBuffer

func (self *VAO) GetIdxBuffer(draw_mode int) (interface{}, int)

func (*VAO) GetInstanceBuffer

func (self *VAO) GetInstanceBuffer() (interface{}, [2]int)

func (*VAO) GetVtxBuffer

func (self *VAO) GetVtxBuffer(draw_mode int, xun int) (interface{}, [4]int)

func (*VAO) ShowInfo

func (self *VAO) ShowInfo()