Added license and documentation

LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2013 Joseph Hager. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -15,7 +15,6 @@ Install
 TODO
 ----
 
-* Wrap up framebuffers
 * Port over 2d shaders and effect composer
 * Port over particle system
 * Create Cache, a static Batch

batch.go

@@ -1,3 +1,7 @@
+// Copyright 2013 Joseph Hager. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package eng
 
 import (
@@ -9,6 +13,36 @@ import (
 const size = 1000
 const degToRad = math.Pi / 180
 
+var batchVert = ` 
+attribute vec4 in_Position;
+attribute vec4 in_Color;
+attribute vec2 in_TexCoords;
+
+uniform mat4 uf_Matrix;
+
+varying vec4 var_Color;
+varying vec2 var_TexCoords;
+
+void main() {
+  var_Color = in_Color;
+  var_TexCoords = in_TexCoords;
+  gl_Position = uf_Matrix * in_Position;
+}
+`
+
+var batchFrag = `
+varying vec4 var_Color;
+varying vec2 var_TexCoords;
+
+uniform sampler2D uf_Texture;
+
+void main (void) {
+  gl_FragColor = var_Color * texture2D (uf_Texture, var_TexCoords);
+}
+`
+
+// A Batch allows geometry to be efficiently rendered by buffering
+// render calls and sending them all at once.
 type Batch struct {
 	drawing          bool
 	lastTexture      *Texture
@@ -32,7 +66,7 @@ type Batch struct {
 
 func NewBatch() *Batch {
 	batch := new(Batch)
-	batch.shader = NewShader(vert, frag)
+	batch.shader = NewShader(batchVert, batchFrag)
 
 	gl.GenBuffers(1, &batch.vertexVBO)
 	gl.BindBuffer(gl.ARRAY_BUFFER, batch.vertexVBO)
@@ -59,6 +93,8 @@ func NewBatch() *Batch {
 	return batch
 }
 
+// Begin calculates the combined matrix and sets up rendering. This
+// must be called before calling Draw.
 func (b *Batch) Begin() {
 	if b.drawing {
 		panic("Batch.End() must be called first")
@@ -67,6 +103,12 @@ func (b *Batch) Begin() {
 	b.drawing = true
 }
 
+// Draw renders a Region with its top left corner at x, y. Scaling and
+// rotation will be with respect to the origin. If color is nil, the
+// current batch color will be used. If the backing texture in the
+// region is different than the last rendered region, any pending
+// geometry will be flushed. Switching textures is a relatively
+// expensive operation.
 func (b *Batch) Draw(r *Region, x, y, originX, originY, scaleX, scaleY, rotation float32, color *Color) {
 	if !b.drawing {
 		panic("Batch.Begin() must be called first")
@@ -196,6 +238,8 @@ func (b *Batch) Draw(r *Region, x, y, originX, originY, scaleX, scaleY, rotation
 	}
 }
 
+// End finishes up rendering and flushes any remaining geometry to the
+// gpu. This must be called after a called to Begin.
 func (b *Batch) End() {
 	if !b.drawing {
 		panic("Batch.Begin() must be called first")
@@ -209,30 +253,46 @@ func (b *Batch) End() {
 	b.drawing = false
 }
 
+// SetBlending will toggle blending for rendering on the batch.
+// Blending is a relatively expensive operation and should be disabled
+// if your goemtry is opaque.
 func (b *Batch) SetBlending(v bool) {
 	if v != b.blendingDisabled {
 		b.flush()
 		b.blendingDisabled = !b.blendingDisabled
 	}
 }
 
+// SetBlendFunc sets the opengl src and dst blending functions. The
+// default is gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA which will render
+// any alpha channel in your textures as blank. Calling this will
+// flush any pending geometry to the gpu.
 func (b *Batch) SetBlendFunc(src, dst gl.Enum) {
 	b.flush()
 	b.blendSrcFunc = src
 	b.blendDstFunc = dst
 }
 
+// SetColor changes the current batch rendering tint. This defaults to white.
 func (b *Batch) SetColor(color *Color) {
 	b.color.R = color.R
 	b.color.G = color.G
 	b.color.B = color.B
 	b.color.A = color.A
 }
 
+// SetShader changes the shader used to rendering geometry. If the
+// passed in shader == nil, the batch will go back to using its
+// default shader. The shader should name the incoming vertex
+// position, color, and texture coordinates to 'in_Position',
+// 'in_Color', and 'in_TexCoords' respectively. The transform projection
+// matrix will be passed in as 'uf_Matrix'.
 func (b *Batch) SetShader(shader *Shader) {
 	b.customShader = shader
 }
 
+// SetProjection allows for setting the projection matrix manually.
+// This is often used with a Camera.
 func (b *Batch) SetProjection(m *Matrix) {
 	b.projection.Set(m)
 }

camera.go

@@ -1,5 +1,11 @@
+// Copyright 2013 Joseph Hager. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package eng
 
+// A Camera represents a viewport with a 2d projection. It allows for
+// simple transformations and zooming.
 type Camera struct {
 	Zoom              float32
 	Position          *Vector
@@ -13,6 +19,7 @@ type Camera struct {
 	ViewportHeight    float32
 }
 
+// NewCamera returns a camera with a viewport of the given width and height.
 func NewCamera(width, height float32) *Camera {
 	camera := new(Camera)
 	camera.Zoom = 1
@@ -30,13 +37,16 @@ func NewCamera(width, height float32) *Camera {
 
 var tmp = new(Vector)
 
+// Update should be called every time the camer is changed in any way.
 func (c *Camera) Update() {
 	c.Projection.SetToOrtho(c.Zoom*-c.ViewportWidth/2, c.Zoom*c.ViewportWidth/2, c.Zoom*c.ViewportHeight/2, c.Zoom*-c.ViewportHeight/2, 0, 1)
 	c.View.SetToLookAt(c.Position, tmp.Set(c.Position).Add(c.Direction), c.Up)
 	c.Combined.Set(c.Projection).Mul(c.View)
 	c.InvProjectionView.Set(c.Combined).Inv()
 }
 
+// Unproject takes a point in screen space and transforms it to be in
+// the view space of the camera.
 func (c *Camera) Unproject(vec *Vector) {
 	viewportWidth := float32(Width())
 	viewportHeight := float32(Height())

canvas.go

@@ -1,19 +1,26 @@
+// Copyright 2013 Joseph Hager. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package eng
 
 import (
 	gl "github.com/chsc/gogl/gl33"
-
 	"image"
 	"log"
 )
 
+// A Canvas technically wraps an opengl framebuffer. It is used to
+// render to a texture that can then be rendered multiple times with a batch.
 type Canvas struct {
 	id      gl.Uint
 	texture *Texture
 	width   int
 	height  int
 }
 
+// NewCanvas constructs a canvas and backing texture with the given
+// width and height.
 func NewCanvas(width, height int) *Canvas {
 	canvas := new(Canvas)
 	canvas.width = width
@@ -42,24 +49,32 @@ func NewCanvas(width, height int) *Canvas {
 	return canvas
 }
 
+// Begin should be called before doing any rendering to the canvas.
 func (c *Canvas) Begin() {
 	gl.Viewport(0, 0, gl.Sizei(c.texture.Width()), gl.Sizei(c.texture.Height()))
 	gl.BindFramebuffer(gl.FRAMEBUFFER, c.id)
 }
 
+// End should be called when done rendering to the canvas.
 func (c *Canvas) End() {
 	gl.Viewport(0, 0, gl.Sizei(Width()), gl.Sizei(Height()))
 	gl.BindFramebuffer(gl.FRAMEBUFFER, 0)
 }
 
+// Texture returns the backing texture that will be rendered to. This
+// can be wrapped in a Region for rendering with a batch. The texture
+// will most likely be flipped upside down. Region.Flip(false, true)
+// can be used when the region is made to deal with that.
 func (c *Canvas) Texture() *Texture {
 	return c.texture
 }
 
+// Width is the width of the canvas.
 func (c *Canvas) Width() int {
 	return c.texture.Width()
 }
 
+// Height is the height of the canvas.
 func (c *Canvas) Height() int {
 	return c.texture.Height()
 }

color.go

@@ -1,3 +1,7 @@
+// Copyright 2013 Joseph Hager. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package eng
 
 import (
@@ -8,10 +12,14 @@ type Color struct {
 	R, G, B, A float32
 }
 
+// NewColor constructs a color using 32bit floating point values in
+// the range 0.0 to 1.0.
 func NewColor(r, g, b, a float32) *Color {
 	return &Color{r, g, b, a}
 }
 
+// NewColorBytes constructs a color using 8bit integers in the the
+// range 0 - 255.
 func NewColorBytes(r, g, b, a byte) *Color {
 	color := new(Color)
 	color.R = float32(r) / 255.0
@@ -30,6 +38,7 @@ func NewColorBytesA(r, g, b byte) *Color {
 	return color
 }
 
+// NewColorRand constructs a random color.
 func NewColorRand() *Color {
 	return &Color{rand.Float32(), rand.Float32(), rand.Float32(), 1}
 }

demos/fbo.go → demos/canvas.go

@@ -11,23 +11,30 @@ var (
 	region *eng.Region
 )
 
-type Hello struct {
+type Game struct {
 	*eng.Game
 }
 
-func (g *Hello) Open() {
+func (g *Game) Init(config *eng.Config) {
+	config.Title = "Canvas"
+}
+
+func (g *Game) Open() {
 	batch = eng.NewBatch()
 	canvas = eng.NewCanvas(eng.Width(), eng.Height())
 	region = eng.NewRegion(canvas.Texture(), 0, 0, eng.Width(), eng.Height())
 	region.Flip(false, true)
 }
 
-func (g *Hello) Draw() {
+func (g *Game) Draw() {
+	x := float32(canvas.Width()/2 - 50)
+	y := float32(canvas.Height() / 2)
+
 	canvas.Begin()
 	batch.Begin()
 	gl.ClearColor(.8, .1, .3, 1)
 	gl.Clear(gl.COLOR_BUFFER_BIT)
-	eng.DefaultFont().Print(batch, "Hello, world!", 430, 280, nil)
+	eng.DefaultFont().Print(batch, "canvas", x, y, nil)
 	batch.End()
 	canvas.End()
 
@@ -37,5 +44,5 @@ func (g *Hello) Draw() {
 }
 
 func main() {
-	eng.Run(new(Hello))
+	eng.Run(new(Game))
 }

demos/hello.go

@@ -4,21 +4,26 @@ import (
 	"github.com/ajhager/eng"
 )
 
-type Hello struct {
+var batch *eng.Batch
+
+type Game struct {
 	*eng.Game
-	batch *eng.Batch
 }
 
-func (g *Hello) Open() {
-	g.batch = eng.NewBatch()
+func (g *Game) Init(config *eng.Config) {
+	config.Title = "Hello"
+}
+
+func (g *Game) Open() {
+	batch = eng.NewBatch()
 }
 
-func (g *Hello) Draw() {
-	g.batch.Begin()
-	eng.DefaultFont().Print(g.batch, "Hello, world!", 430, 280, nil)
-	g.batch.End()
+func (g *Game) Draw() {
+	batch.Begin()
+	eng.DefaultFont().Print(batch, "Hello, world!", 430, 280, nil)
+	batch.End()
 }
 
 func main() {
-	eng.Run(new(Hello))
+	eng.Run(new(Game))
 }