From 77901bb05dbf75e92dd8974ccb23053bb3b2dabf Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Wed, 16 Mar 2022 20:54:19 +0100
Subject: Add docstrings
---
README.md | 1 -
app.go | 5 +++++
geometry.go | 9 +++++----
graphics.go | 5 +++++
main.go | 5 +++++
stl.go | 13 +++++++++----
6 files changed, 29 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 476655c..7f59e5a 100644
--- a/README.md
+++ b/README.md
@@ -43,4 +43,3 @@ To do (most important first):
- [Antons OpenGL tutorial](https://antongerdelan.net/opengl/)
- [OpenGL, GLFW and Go tutorial](https://kylewbanks.com/blog/tutorial-opengl-with-golang-part-1-hello-opengl)
-
diff --git a/app.go b/app.go
index b124f4c..458e9af 100644
--- a/app.go
+++ b/app.go
@@ -15,6 +15,8 @@ const (
WINDOW_TITLE = "stlscope"
)
+// App contains data about the OpenGL application including for example the
+// window, OpenGL graphics and the current STL model.
type App struct {
window *glfw.Window
graphics *Graphics
@@ -22,6 +24,7 @@ type App struct {
homeTrafo mgl32.Mat4
}
+// newApp creates a new App struct based on a given STL model.
func newApp(stl *StlModel) App {
var app App = App{}
@@ -53,6 +56,7 @@ func newApp(stl *StlModel) App {
return app
}
+// handle has to be called frequently to let the App work.
func (application *App) handle() {
glfw.PollEvents()
application.window.SwapBuffers()
@@ -65,6 +69,7 @@ func (application *App) handle() {
application.graphics.setTrafo(trafo)
}
+// terminate closes the App.
func (application App) terminate() {
glfw.Terminate()
}
diff --git a/geometry.go b/geometry.go
index 80420a6..fdbbcef 100644
--- a/geometry.go
+++ b/geometry.go
@@ -6,22 +6,23 @@ import (
"github.com/go-gl/mathgl/mgl32"
)
-// representation of a three-dimensional point in space
+// Point represents a three-dimensional point in space.
type Point struct {
scalars [3]float32 // x = scalars[0], y = scalars[1], z = scalars[2]
}
-// a triangle consists of three points
+// Triangle is a geometrical triangle defined by three points.
type Triangle struct {
points [3]*Point
}
-// a surface is made of a slice of triangles
+// Surface is a slice of triangles.
type Surface struct {
triangles []*Triangle
}
-// return a transformation to view the whole centered surface
+// getHomeView returns a transformation which shows the given Surface in the
+// center of the window.
func (s Surface) getHomeView() mgl32.Mat4 {
// evaluating the smallest and biggest values for x,y,z of the surface
diff --git a/graphics.go b/graphics.go
index a952e40..6c93204 100644
--- a/graphics.go
+++ b/graphics.go
@@ -59,6 +59,7 @@ void main() {
` + "\x00"
)
+// Graphics is a struct to save OpenGL-related data like shaders.
type Graphics struct {
version string
vao uint32
@@ -69,6 +70,7 @@ type Graphics struct {
trafoUniform int32
}
+// newGraphics initializes a new Graphics struct and returns it.
func newGraphics() Graphics {
var graphics Graphics = Graphics{}
@@ -111,6 +113,7 @@ func newGraphics() Graphics {
return graphics
}
+// draw executes the rendering process for a Graphics struct one time.
func (graphics Graphics) draw() {
gl.Clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
gl.UseProgram(graphics.program)
@@ -162,6 +165,7 @@ func makeVao(points []float32, normals []float32) uint32 {
return vao
}
+// compileShaders compiles the shader from source code.
func compileShader(source string, shaderType uint32) (uint32, error) {
log.Println("Compiling shader")
@@ -187,6 +191,7 @@ func compileShader(source string, shaderType uint32) (uint32, error) {
return shader, nil
}
+// setTrafo sets the current transformation matrix of the given Graphics struct.
func (graphics *Graphics) setTrafo(trafo mgl32.Mat4) {
graphics.trafo = trafo
}
diff --git a/main.go b/main.go
index 9c45241..672bb8d 100644
--- a/main.go
+++ b/main.go
@@ -1,5 +1,7 @@
// vim: shiftwidth=4 tabstop=4 noexpandtab
+// stlscope is a file viewer for the STL file format. It is based on Go
+// and OpenGL.
package main
import (
@@ -9,11 +11,13 @@ import (
"io/ioutil"
)
+// cliArgs contains all data given via command line arguments.
type cliArgs struct {
filePath string
debugOutput bool
}
+// main represents the whole functionality of stlscope.
func main() {
// read command line arguments and mute log if necessary
@@ -50,6 +54,7 @@ func main() {
}
}
+// read reads the command line arguments given to stlscope to a cliArgs struct.
func (args *cliArgs) read() {
flag.BoolVar(&args.debugOutput, "debug", false,
"enable to print log output")
diff --git a/stl.go b/stl.go
index 851a003..512d262 100644
--- a/stl.go
+++ b/stl.go
@@ -13,16 +13,17 @@ import (
"math"
)
-// representation of binary STL file content
+// StlModel is the Go-internal representation of a STL model.
type StlModel struct {
header []byte
numberOfTriangles uint32
surface Surface
}
+// Vector3 is a three-dimensional vector based on 32 bit floats.
type Vector3 [3]float32
-// read and parse a given binary STL file
+// ReadBinaryStlFile reads and parses a given binary STL file.
func ReadBinaryStlFile(filePath string) (StlModel, error) {
fileContent, err := ioutil.ReadFile(filePath)
@@ -50,8 +51,8 @@ func ReadBinaryStlFile(filePath string) (StlModel, error) {
return model,nil
}
-// parse the 50 bytes of the STL file representing a triangle (surface normal
-// is ignored)
+// ParseBinaryStlTriangle parses the 50 bytes of the STL file representing a
+// triangle (surface normal is ignored).
func ParseBinaryStlTriangle(data []byte) *Triangle {
// FIXME: This function should only accept 50 byte slices/arrays
@@ -89,6 +90,7 @@ func ParseBinaryStlTriangle(data []byte) *Triangle {
return triangle
}
+// toVertices converts a STL model into vertices suitable for OpenGL rendering.
func (stl StlModel) toVertices() (vertex_position []float32,
vertex_normal []float32) {
@@ -135,12 +137,14 @@ func (stl StlModel) toVertices() (vertex_position []float32,
return vertex_position, vertex_normal
}
+// divideScalar divides a three-dimensional vector by a scalar.
func (vector *Vector3) divideScalar(scalar float32) {
vector[0] = vector[0] / scalar
vector[1] = vector[1] / scalar
vector[2] = vector[2] / scalar
}
+// subtract subtracts vectorB from vectorA.
func (vectorA Vector3) subtract(vectorB Vector3) (vectorC Vector3) {
vectorC[0] = vectorA[0] - vectorB[0]
@@ -150,6 +154,7 @@ func (vectorA Vector3) subtract(vectorB Vector3) (vectorC Vector3) {
return vectorC
}
+// crossProduct returns the cross product vectorA x vectorB.
func (vectorA Vector3) crossProduct(vectorB Vector3) (vectorC Vector3) {
vectorC[0] = vectorA[1] * vectorB[2] - vectorA[2] * vectorB[1]
--
cgit v1.2.3-70-g09d2