From eab91b4110bffa548d498cb9befb0ef0b7cf4fb9 Mon Sep 17 00:00:00 2001
From: faiface <faiface@ksp.sk>
Date: Wed, 15 Mar 2017 22:55:43 +0100
Subject: [PATCH] fix many bugs in pixelgl doc
---
pixelgl/canvas.go | 21 +++++++++++----------
pixelgl/gltriangles.go | 6 ++++--
pixelgl/input.go | 10 +++++-----
pixelgl/run.go | 20 ++++++++------------
pixelgl/window.go | 31 +++++++++++++++----------------
5 files changed, 43 insertions(+), 45 deletions(-)
diff --git a/pixelgl/canvas.go b/pixelgl/canvas.go
index f721855..cb3b4fb 100644
--- a/pixelgl/canvas.go
+++ b/pixelgl/canvas.go
@@ -12,7 +12,8 @@ import (
"github.com/pkg/errors"
)
-// Canvas is an off-screen rectangular BasicTarget that you can draw onto.
+// Canvas is an off-screen rectangular BasicTarget and Picture at the same time, that you can draw
+// onto.
//
// It supports TrianglesPosition, TrianglesColor, TrianglesPicture and PictureColor.
type Canvas struct {
@@ -32,7 +33,7 @@ type Canvas struct {
orig *Canvas
}
-// NewCanvas creates a new empty, fully transparent Canvas with given bounds. If the smooth flag
+// NewCanvas creates a new empty, fully transparent Canvas with given bounds. If the smooth flag is
// set, then stretched Pictures will be smoothed and will not be drawn pixely onto this Canvas.
func NewCanvas(bounds pixel.Rect, smooth bool) *Canvas {
c := &Canvas{
@@ -199,14 +200,14 @@ func (c *Canvas) Bounds() pixel.Rect {
return c.bounds
}
-// SetSmooth sets whether the stretched Pictures drawn onto this Canvas should be drawn smooth or
+// SetSmooth sets whether stretched Pictures drawn onto this Canvas should be drawn smooth or
// pixely.
func (c *Canvas) SetSmooth(smooth bool) {
c.smooth = smooth
}
-// Smooth returns whether the stretched Pictures drawn onto this Canvas are set to be drawn smooth
-// or pixely.
+// Smooth returns whether stretched Pictures drawn onto this Canvas are set to be drawn smooth or
+// pixely.
func (c *Canvas) Smooth() bool {
return c.smooth
}
@@ -219,7 +220,7 @@ func (c *Canvas) setGlhfBounds() {
glhf.Bounds(bx, by, bw, bh)
}
-// Clear fill the whole Canvas with a single color.
+// Clear fills the whole Canvas with a single color.
func (c *Canvas) Clear(color color.Color) {
c.orig.dirty = true
@@ -248,8 +249,8 @@ func (c *Canvas) Clear(color color.Color) {
// Slice returns a sub-Canvas with the specified Bounds.
//
-// The returned value is *Canvas, the type of the return value is a general pixel.Picture just so
-// that Canvas implements pixel.Picture interface.
+// The type of the returned value is *Canvas, the type of the return value is a general
+// pixel.Picture just so that Canvas implements pixel.Picture interface.
func (c *Canvas) Slice(bounds pixel.Rect) pixel.Picture {
sc := new(Canvas)
*sc = *c
@@ -259,8 +260,8 @@ func (c *Canvas) Slice(bounds pixel.Rect) pixel.Picture {
// Original returns the most original Canvas that this Canvas was created from using Slice-ing.
//
-// The returned value is *Canvas, the type of the return value is a general pixel.Picture just so
-// that Canvas implements pixel.Picture interface.
+// The type of the returned value is *Canvas, the type of the return value is a general
+// pixel.Picture just so that Canvas implements pixel.Picture interface.
func (c *Canvas) Original() pixel.Picture {
return c.orig
}
diff --git a/pixelgl/gltriangles.go b/pixelgl/gltriangles.go
index 6958e18..73142f6 100644
--- a/pixelgl/gltriangles.go
+++ b/pixelgl/gltriangles.go
@@ -11,7 +11,7 @@ import (
// GLTriangles are OpenGL triangles implemented using glhf.VertexSlice.
//
// Triangles returned from this function support TrianglesPosition, TrianglesColor and
-// TrianglesTexture. If you need to support more, you can "override" SetLen and Update method.
+// TrianglesPicture. If you need to support more, you can "override" SetLen and Update methods.
type GLTriangles struct {
vs *glhf.VertexSlice
data []float32
@@ -58,6 +58,8 @@ func (gt *GLTriangles) Len() int {
}
// SetLen efficiently resizes GLTriangles to len.
+//
+// Time complexity is amortized O(1).
func (gt *GLTriangles) SetLen(len int) {
if len > gt.Len() {
needAppend := len - gt.Len()
@@ -163,7 +165,7 @@ func (gt *GLTriangles) Update(t pixel.Triangles) {
// Copy returns an independent copy of this GLTriangles.
//
-// The returned Triangles are GLTriangles as the underlying type.
+// The returned Triangles are *GLTriangles as the underlying type.
func (gt *GLTriangles) Copy() pixel.Triangles {
return NewGLTriangles(gt.shader, gt)
}
diff --git a/pixelgl/input.go b/pixelgl/input.go
index 8153534..1af9977 100644
--- a/pixelgl/input.go
+++ b/pixelgl/input.go
@@ -6,27 +6,27 @@ import (
"github.com/go-gl/glfw/v3.2/glfw"
)
-// Pressed returns whether button is currently pressed down.
+// Pressed returns whether the Button is currently pressed down.
func (w *Window) Pressed(button Button) bool {
return w.currInp.buttons[button]
}
-// JustPressed returns whether button has just been pressed down.
+// JustPressed returns whether the Button has just been pressed down.
func (w *Window) JustPressed(button Button) bool {
return w.currInp.buttons[button] && !w.prevInp.buttons[button]
}
-// JustReleased returns whether button has just been released up.
+// JustReleased returns whether the Button has just been released up.
func (w *Window) JustReleased(button Button) bool {
return !w.currInp.buttons[button] && w.prevInp.buttons[button]
}
-// MousePosition returns the current mouse position relative to the window.
+// MousePosition returns the current mouse position in the Window's Bounds.
func (w *Window) MousePosition() pixel.Vec {
return w.currInp.mouse
}
-// MouseScroll returns the scroll amount (in both axis) since the last call to Window.Update.
+// MouseScroll returns the mouse scroll amount (in both axes) since the last call to Window.Update.
func (w *Window) MouseScroll() pixel.Vec {
return w.currInp.scroll
}
diff --git a/pixelgl/run.go b/pixelgl/run.go
index 599c4ab..1c3a2d9 100644
--- a/pixelgl/run.go
+++ b/pixelgl/run.go
@@ -6,27 +6,23 @@ import (
"github.com/pkg/errors"
)
-// Run is essentialy the "main" function of Pixel. It exists mainly due to the technical
-// limitations of OpenGL and operating systems. In short, all graphics and window manipulating
-// calls must be done from the main thread. Run makes this possible.
+// Run is essentialy the main function of PixelGL. It exists mainly due to the technical limitations
+// of OpenGL and operating systems. In short, all graphics and window manipulating calls must be
+// done from the main thread. Run makes this possible.
//
-// Call this function from the main function of your application. This is necessary, so that
-// Run runs on the main thread.
+// Call this function from the main function of your application. This is necessary, so that Run
+// runs on the main thread.
//
// func run() {
-// window := pixel.NewWindow(...)
-// for {
-// // your game's main loop
-// }
+// // interact with Pixel and PixelGL from here (even concurrently)
// }
//
// func main() {
// pixel.Run(run)
// }
//
-// You can spawn any number of goroutines from you run function and interact with Pixel
-// concurrently. The only condition is that the Run function is be called from your main
-// function.
+// You can spawn any number of goroutines from your run function and interact with PixelGL
+// concurrently. The only condition is that the Run function is called from your main function.
func Run(run func()) {
err := glfw.Init()
if err != nil {
diff --git a/pixelgl/window.go b/pixelgl/window.go
index b384c38..885b708 100644
--- a/pixelgl/window.go
+++ b/pixelgl/window.go
@@ -11,11 +11,11 @@ import (
"github.com/pkg/errors"
)
-// WindowConfig is a structure for specifying all possible properties of a window. Properties are
+// WindowConfig is a structure for specifying all possible properties of a Window. Properties are
// chosen in such a way, that you usually only need to set a few of them - defaults (zeros) should
// usually be sensible.
//
-// Note that you always need to set the Bounds of the Window.
+// Note that you always need to set the Bounds of a Window.
type WindowConfig struct {
// Title at the top of the Window.
Title string
@@ -47,7 +47,7 @@ type WindowConfig struct {
VSync bool
}
-// Window is a window handler. Use this type to manipulate a window (input, drawing, ...).
+// Window is a window handler. Use this type to manipulate a window (input, drawing, etc.).
type Window struct {
window *glfw.Window
@@ -142,7 +142,7 @@ func (w *Window) Destroy() {
})
}
-// Update swaps buffers and polls events.
+// Update swaps buffers and polls events. Call this method at the end of each frame.
func (w *Window) Update() {
mainthread.Call(func() {
_, _, oldW, oldH := intBounds(w.bounds)
@@ -207,8 +207,8 @@ func (w *Window) SetTitle(title string) {
})
}
-// SetBounds sets the bounds of the Window in pixels. Bounds can be fractional, but the size will be
-// changed in the next Update to a real possible size of the Window.
+// SetBounds sets the bounds of the Window in pixels. Bounds can be fractional, but the actual size
+// of the window will be rounded to integers.
func (w *Window) SetBounds(bounds pixel.Rect) {
w.bounds = bounds
mainthread.Call(func() {
@@ -268,11 +268,10 @@ func (w *Window) setWindowed() {
}
// SetMonitor sets the Window fullscreen on the given Monitor. If the Monitor is nil, the Window
-// will be resored to windowed state instead.
+// will be restored to windowed state instead.
//
-// Note, that there is nothing about the resolution of the fullscreen Window. The Window is
-// automatically set to the Monitor's resolution. If you want a different resolution, you need
-// to set it manually with SetSize method.
+// The Window will be automatically set to the Monitor's resolution. If you want a different
+// resolution, you will need to set it manually with SetBounds method.
func (w *Window) SetMonitor(monitor *Monitor) {
if w.Monitor() != monitor {
if monitor != nil {
@@ -288,7 +287,7 @@ func (w *Window) IsFullscreen() bool {
return w.Monitor() != nil
}
-// Monitor returns a monitor the Window is fullscreen is on. If the Window is not fullscreen, this
+// Monitor returns a monitor the Window is fullscreen on. If the Window is not fullscreen, this
// function returns nil.
func (w *Window) Monitor() *Monitor {
monitor := mainthread.CallVal(func() interface{} {
@@ -316,21 +315,21 @@ func (w *Window) Focused() bool {
}).(bool)
}
-// Maximize puts the Window window to the maximized state.
+// Maximize puts the Window to the maximized state.
func (w *Window) Maximize() {
mainthread.Call(func() {
w.window.Maximize()
})
}
-// Restore restores the Window window from the maximized state.
+// Restore restores the Window from the maximized state.
func (w *Window) Restore() {
mainthread.Call(func() {
w.window.Restore()
})
}
-// SetVSync sets whether the Window should synchronize with the monitor refresh rate.
+// SetVSync sets whether the Window's Update should synchronize with the monitor refresh rate.
func (w *Window) SetVSync(vsync bool) {
w.vsync = vsync
}
@@ -357,7 +356,7 @@ func (w *Window) end() {
// MakeTriangles generates a specialized copy of the supplied Triangles that will draw onto this
// Window.
//
-// Window supports TrianglesPosition, TrianglesColor and TrianglesTexture.
+// Window supports TrianglesPosition, TrianglesColor and TrianglesPicture.
func (w *Window) MakeTriangles(t pixel.Triangles) pixel.TargetTriangles {
return w.canvas.MakeTriangles(t)
}
@@ -391,7 +390,7 @@ func (w *Window) Smooth() bool {
return w.canvas.Smooth()
}
-// Clear clears the Window with a color.
+// Clear clears the Window with a single color.
func (w *Window) Clear(c color.Color) {
w.canvas.Clear(c)
}
--
GitLab