Merge pull request #204 from oakmound/feature/v4-docs-and-tests

Doc + refactor pass 1 for oak v4

.github/workflows/go.yml

@@ -1,8 +1,30 @@
 name: Go
 on: [push]
 jobs:
-  test-arm:
-    name: Test (arm)
+  test-windows-x64:
+    name: Test (windows amd64)
+    runs-on: [self-hosted, windows, x64]
+    steps:
+
+    - name: Set up Go 1.18
+      uses: actions/setup-go@v1
+      with:
+        go-version: 1.18
+      id: go
+
+    - name: Check out code into the Go module directory
+      uses: actions/checkout@v1
+
+    - name: Get dependencies
+      run: |
+        go get -v -t -d ./...
+
+    - name: Test
+      run: ./test_examples.sh
+      shell: bash
+
+  test-linux-arm:
+    name: Test (linux arm)
     runs-on: [self-hosted, linux, ARM64]
     steps:
 
@@ -22,6 +44,27 @@ jobs:
     - name: Test
       run: ./test_examples.sh
 
+  test-linux-x64:
+    name: Test (linux x64)
+    runs-on: [self-hosted, linux, x64]
+    steps:
+
+    - name: Set up Go 1.18
+      uses: actions/setup-go@v1
+      with:
+        go-version: 1.18
+      id: go
+
+    - name: Check out code into the Go module directory
+      uses: actions/checkout@v1
+
+    - name: Get dependencies
+      run: |
+        go get -v -t -d ./...
+
+    - name: Test
+      run: ./test_examples.sh
+
   test:
     name: Test
     runs-on: ubuntu-latest

README.md

@@ -2,7 +2,7 @@
 
 ## A Pure Go game engine
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/oakmound/oak/v3.svg)](https://pkg.go.dev/github.com/oakmound/oak/v3)
+[![Go Reference](https://pkg.go.dev/badge/github.com/oakmound/oak/v4.svg)](https://pkg.go.dev/github.com/oakmound/oak/v4)
 [![Code Coverage](https://codecov.io/gh/oakmound/oak/branch/develop/graph/badge.svg)](https://codecov.io/gh/oakmound/oak)
 [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)
 
@@ -24,14 +24,14 @@
 
 ## Installation <a name="installation"/>
 
-`go get -u github.com/oakmound/oak/v3`
+`go get -u github.com/oakmound/oak/v4`
 
 ## Features and Systems <a name="features"></a>
 
 1. Window Management
     - Windows and key events forked from [shiny](https://pkg.go.dev/golang.org/x/exp/shiny)
     - Support for multiple windows running at the same time
-1. [Image Rendering](https://pkg.go.dev/github.com/oakmound/oak/v3/render)
+1. [Image Rendering](https://pkg.go.dev/github.com/oakmound/oak/v4/render)
     - Manipulation
         - `render.Modifiable` interface
         - Integrated with optimized image manipulation via [gift](https://github.com/disintegration/gift)
@@ -40,18 +40,18 @@
         - Primitive builders, `ColorBox`, `Line`, `Bezier`
         - History-tracking `Reverting`
     - Primarily 2D
-1. [Particle System](https://pkg.go.dev/github.com/oakmound/oak/v3/render/particle)
-1. [Mouse Handling](https://pkg.go.dev/github.com/oakmound/oak/v3/mouse)
-1. [Joystick Support](https://pkg.go.dev/github.com/oakmound/oak/v3/joystick)
-1. [Audio Support](https://pkg.go.dev/github.com/oakmound/oak/v3/audio)
-1. [Collision](https://pkg.go.dev/github.com/oakmound/oak/v3/collision)
+1. [Particle System](https://pkg.go.dev/github.com/oakmound/oak/v4/render/particle)
+1. [Mouse Handling](https://pkg.go.dev/github.com/oakmound/oak/v4/mouse)
+1. [Joystick Support](https://pkg.go.dev/github.com/oakmound/oak/v4/joystick)
+1. [Audio Support](https://pkg.go.dev/github.com/oakmound/oak/v4/audio)
+1. [Collision](https://pkg.go.dev/github.com/oakmound/oak/v4/collision)
     - Collision R-Tree forked from [rtreego](https://github.com/dhconnelly/rtreego)
-    - [2D Raycasting](https://pkg.go.dev/github.com/oakmound/oak/v3/collision/ray)
+    - [2D Raycasting](https://pkg.go.dev/github.com/oakmound/oak/v4/collision/ray)
     - Collision Spaces
         - Attachable to Objects
         - Auto React to collisions through events
-1. [2D Physics System](https://pkg.go.dev/github.com/oakmound/oak/v3/physics)
-1. [Event Handler](https://pkg.go.dev/github.com/oakmound/oak/v3/event)
+1. [2D Physics System](https://pkg.go.dev/github.com/oakmound/oak/v4/physics)
+1. [Event Handler](https://pkg.go.dev/github.com/oakmound/oak/v4/event)
 
 ## Support <a name="support"></a>
 
@@ -65,8 +65,8 @@ This is an example of the most basic oak program:
 package main
 
 import (
-    "github.com/oakmound/oak/v3"
-    "github.com/oakmound/oak/v3/scene"
+    "github.com/oakmound/oak/v4"
+    "github.com/oakmound/oak/v4/scene"
 )
 
 func main() {
@@ -79,7 +79,7 @@ func main() {
 }
 ```
 
-See below or the [examples](examples) folder for longer demos, [godoc](https://pkg.go.dev/github.com/oakmound/oak/v3) for reference documentation, and the [wiki](https://github.com/oakmound/oak/wiki) for more guided tutorials and walkthroughs.
+See below or the [examples](examples) folder for longer demos, [godoc](https://pkg.go.dev/github.com/oakmound/oak/v4) for reference documentation, and the [wiki](https://github.com/oakmound/oak/wiki) for more guided tutorials and walkthroughs.
 
 ## Examples <a name="examples"></a>
 

alg/floatgeom/point.go

@@ -3,7 +3,7 @@ package floatgeom
 import (
 	"math"
 
-	"github.com/oakmound/oak/v3/alg"
+	"github.com/oakmound/oak/v4/alg"
 )
 
 // Point2 represents a 2D point on a plane.

alg/floatgeom/point_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/oakmound/oak/v3/alg"
+	"github.com/oakmound/oak/v4/alg"
 )
 
 func Seed() {

alg/floatgeom/polygon.go

@@ -1,7 +1,7 @@
 package floatgeom
 
 import (
-	"github.com/oakmound/oak/v3/alg"
+	"github.com/oakmound/oak/v4/alg"
 )
 
 // A Polygon2 is a series of points in 2D space.

alg/intgeom/point.go

@@ -3,7 +3,7 @@ package intgeom
 import (
 	"math"
 
-	"github.com/oakmound/oak/v3/alg"
+	"github.com/oakmound/oak/v4/alg"
 )
 
 // Point2 represents a 2D point in space.

alg/intgeom/point_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/oakmound/oak/v3/alg"
+	"github.com/oakmound/oak/v4/alg"
 )
 
 func Seed() {

alg/intgeom/rect.go

@@ -1,5 +1,11 @@
 package intgeom
 
+import (
+	"math/rand"
+
+	"github.com/oakmound/oak/v4/alg/span"
+)
+
 // A Rect2 represents a span from one point in 2D space to another.
 // If Min is less than max on any axis, it will return undefined results
 // for methods.
@@ -326,3 +332,93 @@ func (r Rect2) Intersects(r2 Rect2) bool {
 	return !((r2.Max.X() <= r.Min.X() || r.Max.X() <= r2.Min.X()) ||
 		(r2.Max.Y() <= r.Min.Y() || r.Max.Y() <= r2.Min.Y()))
 }
+
+// MulConst multiplies the boundary points of this rectangle by i.
+func (r Rect2) MulConst(i int) Rect2 {
+	return Rect2{
+		r.Min.MulConst(i),
+		r.Max.MulConst(i),
+	}
+}
+
+// Poll returns a pseudorandom point from within this rectangle
+func (r Rect2) Poll() Point2 {
+	return Point2{
+		r.Min.X() + int(rand.Float64()*float64(r.W())),
+		r.Min.Y() + int(rand.Float64()*float64(r.H())),
+	}
+}
+
+// Clamp returns a version of the provided point such that it is contained within r. If it was already contained in
+// r, it will not be changed.
+func (r Rect2) Clamp(pt Point2) Point2 {
+	for i := 0; i < r.MaxDimensions(); i++ {
+		if pt[i] < r.Min[i] {
+			pt[i] = r.Min[i]
+		} else if pt[i] > r.Max[i] {
+			pt[i] = r.Max[i]
+		}
+	}
+	return pt
+}
+
+// Percentile returns a point within this rectangle along the vector from the top left to the bottom right of the
+// rectangle, where for example, 0.0 will be r.Min, 1.0 will be r.Max, and 2.0 will be project the vector beyond r
+// and return r.Min + {r.W()*2, r.H()*2}
+func (r Rect2) Percentile(f float64) Point2 {
+	return Point2{
+		r.Min.X() + int(f*float64(r.W())),
+		r.Min.Y() + int(f*float64(r.H())),
+	}
+}
+
+// MulSpan returns this rectangle as a Point2 Span after multiplying the boundary points of the rectangle by f.
+func (r Rect2) MulSpan(f float64) span.Span[Point2] {
+	return r.MulConst(int(f))
+}
+
+// MulConst multiplies the boundary points of this rectangle by i.
+func (r Rect3) MulConst(i int) Rect3 {
+	return Rect3{
+		r.Min.MulConst(i),
+		r.Max.MulConst(i),
+	}
+}
+
+// Poll returns a pseudorandom point from within this rectangle
+func (r Rect3) Poll() Point3 {
+	return Point3{
+		r.Min.X() + int(rand.Float64()*float64(r.W())),
+		r.Min.Y() + int(rand.Float64()*float64(r.H())),
+		r.Min.Z() + int(rand.Float64()*float64(r.D())),
+	}
+}
+
+// Clamp returns a version of the provided point such that it is contained within r. If it was already contained in
+// r, it will not be changed.
+func (r Rect3) Clamp(pt Point3) Point3 {
+	for i := 0; i < r.MaxDimensions(); i++ {
+		if pt[i] < r.Min[i] {
+			pt[i] = r.Min[i]
+		} else if pt[i] > r.Max[i] {
+			pt[i] = r.Max[i]
+		}
+	}
+	return pt
+}
+
+// Percentile returns a point within this rectangle along the vector from the top left to the bottom right of the
+// rectangle, where for example, 0.0 will be r.Min, 1.0 will be r.Max, and 2.0 will be project the vector beyond r
+// and return r.Min + {r.W()*2, r.H()*2, r.D()*2}
+func (r Rect3) Percentile(f float64) Point3 {
+	return Point3{
+		r.Min.X() + int(f*float64(r.W())),
+		r.Min.Y() + int(f*float64(r.H())),
+		r.Min.Z() + int(f*float64(r.D())),
+	}
+}
+
+// MulConst multiplies the boundary points of this rectangle by i.
+func (r Rect3) MulSpan(f float64) span.Span[Point3] {
+	return r.MulConst(int(f))
+}

alg/intgeom/rect_test.go

@@ -239,3 +239,67 @@ func TestRect3GreaterOf(t *testing.T) {
 		}
 	}
 }
+
+func TestRect2Span(t *testing.T) {
+	t.Run("Basic", func(t *testing.T) {
+		r := NewRect2WH(1, 1, 9, 9)
+		p1 := r.Percentile(1.0)
+		if p1 != r.Max {
+			t.Errorf("Percentile(1.0) did not return max point: got %v expected %v", p1, r.Max)
+		}
+		p2 := r.Percentile(0.0)
+		if p2 != r.Min {
+			t.Errorf("Percentile(0.0) did not return min point: got %v expected %v", p2, r.Min)
+		}
+		const pollTries = 100
+		for i := 0; i < pollTries; i++ {
+			if !r.Contains(r.Poll()) {
+				t.Fatalf("polled point did not lie within the creating rectangle")
+			}
+		}
+		p3 := r.Clamp(Point2{0, 5})
+		if p3 != (Point2{1, 5}) {
+			t.Errorf("Clamp(0,5) did not return {1,5}: got %v", p3)
+		}
+		p4 := r.Clamp(Point2{2, 11})
+		if p4 != (Point2{2, 10}) {
+			t.Errorf("Clamp(2,11) did not return {2,10}: got %v", p4)
+		}
+		r2 := r.MulSpan(4)
+		if r2 != NewRect2(4, 4, 40, 40) {
+			t.Errorf("MulSpan did not return {4,4,40,40}: got %v", r2)
+		}
+	})
+}
+
+func TestRect3Span(t *testing.T) {
+	t.Run("Basic", func(t *testing.T) {
+		r := NewRect3WH(1, 1, 1, 9, 9, 9)
+		p1 := r.Percentile(1.0)
+		if p1 != r.Max {
+			t.Errorf("Percentile(1.0) did not return max point: got %v expected %v", p1, r.Max)
+		}
+		p2 := r.Percentile(0.0)
+		if p2 != r.Min {
+			t.Errorf("Percentile(0.0) did not return min point: got %v expected %v", p2, r.Min)
+		}
+		const pollTries = 100
+		for i := 0; i < pollTries; i++ {
+			if !r.Contains(r.Poll()) {
+				t.Fatalf("polled point did not lie within the creating rectangle")
+			}
+		}
+		p3 := r.Clamp(Point3{0, -1, 5})
+		if p3 != (Point3{1, 1, 5}) {
+			t.Errorf("Clamp(0,-1,5) did not return {1,1,5}: got %v", p3)
+		}
+		p4 := r.Clamp(Point3{20, 2, 11})
+		if p4 != (Point3{10, 2, 10}) {
+			t.Errorf("Clamp(20, 2,11) did not return {10,2,10}: got %v", p4)
+		}
+		r2 := r.MulSpan(4)
+		if r2 != NewRect3(4, 4, 4, 40, 40, 40) {
+			t.Errorf("MulSpan did not return {4,4,4,40,40,40}: got %v", r2)
+		}
+	})
+}