From ceceed951f8ac0428245c8d24b356467560b3cd8 Mon Sep 17 00:00:00 2001
From: Hajime Hoshi <hajimehoshi@gmail.com>
Date: Fri, 22 Sep 2017 01:13:37 +0900
Subject: [PATCH] graphics: Add comments

---
 internal/graphics/command.go     | 10 +---------
 internal/graphics/framebuffer.go | 34 ++++++++++++++++++++++++++++++--
 internal/graphics/image.go       |  2 ++
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/internal/graphics/command.go b/internal/graphics/command.go
index 26779dd48..661c3888f 100644
--- a/internal/graphics/command.go
+++ b/internal/graphics/command.go
@@ -423,14 +423,6 @@ func (c *newScreenFramebufferImageCommand) Exec(indexOffsetInBytes int) error {
 	if c.height < 1 {
 		return errors.New("graphics: height must be equal or more than 1.")
 	}
-	f := &framebuffer{
-		native:  opengl.GetContext().ScreenFramebuffer(),
-		flipY:   true,
-		width:   c.width,
-		height:  c.height,
-		offsetX: c.offsetX,
-		offsetY: c.offsetY,
-	}
-	c.result.framebuffer = f
+	c.result.framebuffer = newScreenFramebuffer(c.width, c.height, c.offsetX, c.offsetY)
 	return nil
 }
diff --git a/internal/graphics/framebuffer.go b/internal/graphics/framebuffer.go
index 16cfa04e0..2c3e0ef57 100644
--- a/internal/graphics/framebuffer.go
+++ b/internal/graphics/framebuffer.go
@@ -19,6 +19,9 @@ import (
 	"github.com/hajimehoshi/ebiten/internal/web"
 )
 
+// orthoProjectionMatrix returns an orthogonal projection matrix for OpenGL.
+//
+// The matrix converts the coodinates (left, bottom) - (right, top) to the normalized device coodinates (-1, -1) - (1, 1).
 func orthoProjectionMatrix(left, right, bottom, top int) []float32 {
 	e11 := 2 / float32(right-left)
 	e22 := 2 / float32(top-bottom)
@@ -33,16 +36,21 @@ func orthoProjectionMatrix(left, right, bottom, top int) []float32 {
 	}
 }
 
+// framebuffer is a wrapper of OpenGL's framebuffer.
 type framebuffer struct {
 	native    opengl.Framebuffer
 	flipY     bool
 	proMatrix []float32
 	width     int
 	height    int
-	offsetX   float64
-	offsetY   float64
+
+	// offsetX and offsetY are translation part of the projection matrix.
+	// offsetX and offsetY are used for the fullscreen mode.
+	offsetX float64
+	offsetY float64
 }
 
+// newFramebufferFromTexture creates a framebuffer from the given texture.
 func newFramebufferFromTexture(texture *texture, width, height int) (*framebuffer, error) {
 	native, err := opengl.GetContext().NewFramebuffer(opengl.Texture(texture.native))
 	if err != nil {
@@ -55,8 +63,24 @@ func newFramebufferFromTexture(texture *texture, width, height int) (*framebuffe
 	}, nil
 }
 
+// newScreenFramebuffer creates a framebuffer for the screen.
+func newScreenFramebuffer(width, height int, offsetX, offsetY float64) *framebuffer {
+	return &framebuffer{
+		native:  opengl.GetContext().ScreenFramebuffer(),
+		flipY:   true,
+		width:   width,
+		height:  height,
+		offsetX: offsetX,
+		offsetY: offsetY,
+	}
+}
+
+// defaultViewportSize is the default size (width or height) of viewport.
+//
+// defaultViewportSize also represents the maximum size of a framebuffer.
 const defaultViewportSize = 4096
 
+// viewportSize returns the viewport size of the framebuffer.
 func (f *framebuffer) viewportSize() (int, int) {
 	// On some browsers, viewport size must be within the framebuffer size.
 	// e.g. Edge (#71), Chrome on GPD Pocket (#420)
@@ -68,11 +92,17 @@ func (f *framebuffer) viewportSize() (int, int) {
 	return defaultViewportSize, defaultViewportSize
 }
 
+// setAsViewport sets the framebuffer as the current viewport.
 func (f *framebuffer) setAsViewport() error {
 	w, h := f.viewportSize()
 	return opengl.GetContext().SetViewport(f.native, w, h)
 }
 
+// projectionMatrix returns a projection matrix of the framebuffer.
+//
+// A projection matrix converts the coodinates on the framebuffer
+// (0, 0) - (viewport width, viewport height)
+// to the normalized device coodinates (-1, -1) - (1, 1) with adjustment.
 func (f *framebuffer) projectionMatrix(height int) []float32 {
 	if f.proMatrix != nil {
 		return f.proMatrix
diff --git a/internal/graphics/image.go b/internal/graphics/image.go
index 9c1ee29a0..430141499 100644
--- a/internal/graphics/image.go
+++ b/internal/graphics/image.go
@@ -22,6 +22,7 @@ import (
 	"github.com/hajimehoshi/ebiten/internal/opengl"
 )
 
+// Image represents an image that is implemented with OpenGL.
 type Image struct {
 	texture     *texture
 	framebuffer *framebuffer
@@ -29,6 +30,7 @@ type Image struct {
 	height      int
 }
 
+// MaxImageSize is the maximum of width/height of an image.
 const MaxImageSize = defaultViewportSize
 
 func NewImage(width, height int, filter opengl.Filter) *Image {