interesting
/
go-opengl-pixel
mirror of https://github.com/faiface/pixel.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

improve doc in pixel

This commit is contained in:
faiface 2017-01-25 18:55:17 +01:00
parent 4a31512454
commit bc97fa00b8
10 changed files with 79 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
batch.go
View File

@ -53,13 +53,11 @@ func (b *Batch) MakeTriangles(t Triangles) Triangles {
}
}
// SetPicture sets the current Picture that will be used with the following draws. The underlying
// Texture of this Picture must be same as the underlying Texture of the Batch's Picture.
// SetPicture sets the current Picture that will be used with the following draws. The original
// Picture of this Picture (the one from which p was obtained by slicing) must be same as the
// original Picture of the Batch's Picture.
func (b *Batch) SetPicture(p *Picture) {
if p == nil {
return
}
if p.Texture() != b.fixpic.Texture() {
if p != nil && p.Texture() != b.fixpic.Texture() {
panic("batch: attempted to draw with a different underlying Picture")
}
b.pic = p

9
canvas.go
View File

@ -9,7 +9,7 @@ import (
"github.com/pkg/errors"
)
// Canvas is basically a Picture that you can draw on.
// Canvas is basically a Picture that you can draw onto.
//
// Canvas supports TrianglesPosition, TrianglesColor and TrianglesTexture.
type Canvas struct {
@ -72,7 +72,7 @@ func NewCanvas(width, height float64, smooth bool) *Canvas {
return c
}
// SetSize resizes the Canvas. The original content will be stretched to the new size.
// SetSize resizes the Canvas. The original content will be stretched to fit the new size.
func (c *Canvas) SetSize(width, height float64) {
if V(width, height) == V(c.Size()) {
return
@ -105,7 +105,8 @@ func (c *Canvas) Size() (width, height float64) {
}
// Content returns a Picture that contains the content of this Canvas. The returned Picture changes
// as you draw onto the Canvas, so there is no real need to call this method more than once.
// as you draw onto the Canvas, so there is no real need to call this method more than once (but it
// might be beneficial to your code to do so).
func (c *Canvas) Content() *Picture {
tex := c.f.Texture()
return &Picture{
@ -114,7 +115,7 @@ func (c *Canvas) Content() *Picture {
}
}
// Clear fill the whole Canvas with on specified color.
// Clear fills the whole Canvas with one specified color.
func (c *Canvas) Clear(col color.Color) {
mainthread.CallNonBlock(func() {
c.f.Begin()

2
color.go
View File

@ -52,7 +52,7 @@ func (c NRGBA) Scaled(scale float64) NRGBA {
}
}
// RGBA returns alpha-premultiplied red, green, blue and alpha components of a color.
// RGBA returns alpha-premultiplied red, green, blue and alpha components of the NRGBA color.
func (c NRGBA) RGBA() (r, g, b, a uint32) {
c.R = clamp(c.R, 0, 1)
c.G = clamp(c.G, 0, 1)

36
geometry.go
View File

@ -6,7 +6,7 @@ import (
"math/cmplx"
)
// Vec is a 2d vector type. It is unusually implemented as complex128 for convenience. Since
// Vec is a 2D vector type. It is unusually implemented as complex128 for convenience. Since
// Go does not allow operator overloading, implementing vector as a struct leads to a bunch of
// methods for addition, subtraction and multiplication of vectors. With complex128, much of
// this functionality is given through operators.
@ -37,7 +37,7 @@ func V(x, y float64) Vec {
return Vec(complex(x, y))
}
// String returns the string representation of a vector u.
// String returns the string representation of the vector u.
//
// u := pixel.V(4.5, -1.3)
// u.String() // returns "Vec(4.5, -1.3)"
@ -46,27 +46,27 @@ func (u Vec) String() string {
return fmt.Sprintf("Vec(%v, %v)", u.X(), u.Y())
}
// X returns the x coordinate of a vector u.
// X returns the x coordinate of the vector u.
func (u Vec) X() float64 {
return real(u)
}
// Y returns the y coordinate of a vector u.
// Y returns the y coordinate of the vector u.
func (u Vec) Y() float64 {
return imag(u)
}
// XY returns the components of a vector in two return values.
// XY returns the components of the vector in two return values.
func (u Vec) XY() (x, y float64) {
return real(u), imag(u)
}
// Len returns the length of a vector u.
// Len returns the length of the vector u.
func (u Vec) Len() float64 {
return cmplx.Abs(complex128(u))
}
// Angle returns the angle between a vector u and the x-axis. The result is in the range [-Pi, Pi].
// Angle returns the angle between the vector u and the x-axis. The result is in the range [-Pi, Pi].
func (u Vec) Angle() float64 {
return cmplx.Phase(complex128(u))
}
@ -76,12 +76,12 @@ func (u Vec) Unit() Vec {
return u / V(u.Len(), 0)
}
// Scaled returns a vector u multiplied by c.
// Scaled returns the vector u multiplied by c.
func (u Vec) Scaled(c float64) Vec {
return u * V(c, 0)
}
// Rotated returns a vector u rotated by the given angle in radians.
// Rotated returns the vector u rotated by the given angle in radians.
func (u Vec) Rotated(angle float64) Vec {
sin, cos := math.Sincos(angle)
return u * V(cos, sin)
@ -97,7 +97,7 @@ func (u Vec) Cross(v Vec) float64 {
return u.X()*v.Y() - v.X()*u.Y()
}
// Rect is a 2d rectangle aligned with the axis of the coordinate system. It has a position
// Rect is a 2D rectangle aligned with the axes of the coordinate system. It has a position
// and a size.
//
// You can manipulate the position and the size using the usual vector operations.
@ -105,7 +105,7 @@ type Rect struct {
Pos, Size Vec
}
// R returns a new 2d rectangle with the given position (x, y) and size (w, h).
// R returns a new Rect with given position (x, y) and size (w, h).
func R(x, y, w, h float64) Rect {
return Rect{
Pos: V(x, y),
@ -113,7 +113,7 @@ func R(x, y, w, h float64) Rect {
}
}
// String returns the string representation of a rectangle.
// String returns the string representation of the rectangle.
//
// r := pixel.R(100, 50, 200, 300)
// r.String() // returns "Rect(100, 50, 200, 300)"
@ -122,32 +122,32 @@ func (r Rect) String() string {
return fmt.Sprintf("Rect(%v, %v, %v, %v)", r.X(), r.Y(), r.W(), r.H())
}
// X returns the x coordinate of the position of a rectangle.
// X returns the x coordinate of the position of the rectangle.
func (r Rect) X() float64 {
return r.Pos.X()
}
// Y returns the y coordinate of the position of a rectangle
// Y returns the y coordinate of the position of the rectangle
func (r Rect) Y() float64 {
return r.Pos.Y()
}
// W returns the width of a rectangle.
// W returns the width of the rectangle.
func (r Rect) W() float64 {
return r.Size.X()
}
// H returns the height of a rectangle.
// H returns the height of the rectangle.
func (r Rect) H() float64 {
return r.Size.Y()
}
// XYWH returns all of the four components of a rectangle in four return values.
// XYWH returns all of the four components of the rectangle in four return values.
func (r Rect) XYWH() (x, y, w, h float64) {
return r.X(), r.Y(), r.W(), r.H()
}
// Center returns the position of the center of a rectangle.
// Center returns the position of the center of the rectangle.
func (r Rect) Center() Vec {
return r.Pos + r.Size.Scaled(0.5)
}

6
input.go
View File

@ -5,17 +5,17 @@ import (
"github.com/go-gl/glfw/v3.2/glfw"
)
// Pressed returns whether a button is currently pressed down.
// Pressed returns whether button is currently pressed down.
func (w *Window) Pressed(button Button) bool {
return w.currInp.buttons[button]
}
// JustPressed returns whether a button has just been pressed down.
// JustPressed returns whether 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 a button has just been released up.
// JustReleased returns whether button has just been released up.
func (w *Window) JustReleased(button Button) bool {
return !w.currInp.buttons[button] && w.prevInp.buttons[button]
}

2
interface.go
View File

@ -6,6 +6,8 @@ import "image/color"
//
// You can notice, that there are no "drawing" methods in a Target. That's because all drawing
// happens indirectly through Triangles instance generated via MakeTriangles method.
//
// If no transforms are applied, the drawing are of a Target is the rectangle (-1, -1, +1, +1).
type Target interface {
// MakeTriangles generates a specialized copy of the provided Triangles.
//

12
monitor.go
View File

@ -31,7 +31,7 @@ func Monitors() []*Monitor {
return monitors
}
// Name returns a human-readable name of a monitor.
// Name returns a human-readable name of the Monitor.
func (m *Monitor) Name() string {
name := mainthread.CallVal(func() interface{} {
return m.monitor.GetName()
@ -39,7 +39,7 @@ func (m *Monitor) Name() string {
return name
}
// PhysicalSize returns the size of the display area of a monitor in millimeters.
// PhysicalSize returns the size of the display area of the Monitor in millimeters.
func (m *Monitor) PhysicalSize() (width, height float64) {
var wi, hi int
mainthread.Call(func() {
@ -50,7 +50,7 @@ func (m *Monitor) PhysicalSize() (width, height float64) {
return
}
// Position returns the position of the upper-left corner of a monitor in screen coordinates.
// Position returns the position of the upper-left corner of the Monitor in screen coordinates.
func (m *Monitor) Position() (x, y float64) {
var xi, yi int
mainthread.Call(func() {
@ -61,7 +61,7 @@ func (m *Monitor) Position() (x, y float64) {
return
}
// Size returns the resolution of a monitor in pixels.
// Size returns the resolution of the Monitor in pixels.
func (m *Monitor) Size() (width, height float64) {
mode := mainthread.CallVal(func() interface{} {
return m.monitor.GetVideoMode()
@ -71,7 +71,7 @@ func (m *Monitor) Size() (width, height float64) {
return
}
// BitDepth returns the number of bits per color of a monitor.
// BitDepth returns the number of bits per color of the Monitor.
func (m *Monitor) BitDepth() (red, green, blue int) {
mode := mainthread.CallVal(func() interface{} {
return m.monitor.GetVideoMode()
@ -82,7 +82,7 @@ func (m *Monitor) BitDepth() (red, green, blue int) {
return
}
// RefreshRate returns the refresh frequency of a monitor in Hz (refreshes/second).
// RefreshRate returns the refresh frequency of the Monitor in Hz (refreshes/second).
func (m *Monitor) RefreshRate() (rate float64) {
mode := mainthread.CallVal(func() interface{} {
return m.monitor.GetVideoMode()

22
picture.go
View File

@ -10,15 +10,15 @@ import (
// Picture is a raster picture. It is usually used with sprites.
//
// A picture is created from an image.Image, that can be either loaded from a file, or
// generated. After the creation a picture can be sliced (slicing creates a "sub-picture"
// from a picture) into smaller pictures.
// A Picture is created from an image.Image, that can be either loaded from a file, or
// generated. After the creation, Pictures can be sliced (slicing creates a "sub-Picture"
// from a Picture) into smaller Pictures.
type Picture struct {
texture *pixelgl.Texture
bounds Rect
}
// NewPicture creates a new picture from an image.Image.
// NewPicture creates a new Picture from an image.Image.
func NewPicture(img image.Image, smooth bool) *Picture {
// convert the image to NRGBA format
bounds := img.Bounds()
@ -80,16 +80,16 @@ func (p *Picture) Image() *image.NRGBA {
return nrgba
}
// Texture returns a pointer to the underlying OpenGL texture of a picture.
// Texture returns a pointer to the underlying OpenGL texture of the Picture.
func (p *Picture) Texture() *pixelgl.Texture {
return p.texture
}
// Slice returns a picture within the supplied rectangle of the original picture. The original
// and the sliced picture share the same texture.
// Slice returns a Picture within the supplied rectangle of the original picture. The original
// and the sliced Picture share the same texture.
//
// For example, suppose we have a 100x200 pixels picture. If we slice it with rectangle (50,
// 100, 50, 100), we get the upper-right quadrant of the original picture.
// For example, suppose we have a 100x200 pixels Picture. If we slice it with rectangle (50,
// 100, 50, 100), we get the upper-right quadrant of the original Picture.
func (p *Picture) Slice(slice Rect) *Picture {
return &Picture{
texture: p.texture,
@ -97,9 +97,9 @@ func (p *Picture) Slice(slice Rect) *Picture {
}
}
// Bounds returns the bounding rectangle of this picture relative to the most original picture.
// Bounds returns the bounding rectangle of this Picture relative to the most original picture.
//
// If the original picture gets sliced with the return value of this method, this picture will
// If the original Picture was sliced with the return value of this method, this Picture would
// be obtained.
func (p *Picture) Bounds() Rect {
return p.bounds

4
run.go
View File

@ -6,7 +6,7 @@ import (
)
// 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
// 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
@ -24,7 +24,7 @@ import (
// }
//
// You can spawn any number of goroutines from you run function and interact with Pixel
// concurrently. The only condition is that the Run function must be called from your main
// concurrently. The only condition is that the Run function is be called from your main
// function.
func Run(run func()) {
defer glfw.Terminate()

54
window.go
View File

@ -77,9 +77,9 @@ type Window struct {
var currentWindow *Window
// NewWindow creates a new window with it's properties specified in the provided config.
// NewWindow creates a new Window with it's properties specified in the provided config.
//
// If window creation fails, an error is returned.
// If Window creation fails, an error is returned (e.g. due to unavailable graphics device).
func NewWindow(config WindowConfig) (*Window, error) {
bool2int := map[bool]int{
true: glfw.True,
@ -164,14 +164,14 @@ func NewWindow(config WindowConfig) (*Window, error) {
return w, nil
}
// Destroy destroys a window. The window can't be used any further.
// Destroy destroys the Window. The Window can't be used any further.
func (w *Window) Destroy() {
mainthread.Call(func() {
w.window.Destroy()
})
}
// Clear clears the window with a color.
// Clear clears the Window with a color.
func (w *Window) Clear(c color.Color) {
w.canvas.Clear(c)
}
@ -202,41 +202,41 @@ func (w *Window) Update() {
w.updateInput()
}
// SetClosed sets the closed flag of a window.
// SetClosed sets the closed flag of the Window.
//
// This is usefull when overriding the user's attempt to close a window, or just to close a
// window from within a program.
// This is usefull when overriding the user's attempt to close the Window, or just to close the
// Window from within the program.
func (w *Window) SetClosed(closed bool) {
mainthread.Call(func() {
w.window.SetShouldClose(closed)
})
}
// Closed returns the closed flag of a window, which reports whether the window should be closed.
// Closed returns the closed flag of the Window, which reports whether the Window should be closed.
//
// The closed flag is automatically set when a user attempts to close a window.
// The closed flag is automatically set when a user attempts to close the Window.
func (w *Window) Closed() bool {
return mainthread.CallVal(func() interface{} {
return w.window.ShouldClose()
}).(bool)
}
// SetTitle changes the title of a window.
// SetTitle changes the title of the Window.
func (w *Window) SetTitle(title string) {
mainthread.Call(func() {
w.window.SetTitle(title)
})
}
// SetSize resizes a window to the specified size in pixels. In case of a fullscreen window,
// it changes the resolution of that window.
// SetSize resizes the client area of the Window to the specified size in pixels. In case of a
// fullscreen Window, it changes the resolution of that Window.
func (w *Window) SetSize(width, height float64) {
mainthread.Call(func() {
w.window.SetSize(int(width), int(height))
})
}
// Size returns the size of the client area of a window (the part you can draw on).
// Size returns the size of the client area of the Window (the part you can draw on).
func (w *Window) Size() (width, height float64) {
mainthread.Call(func() {
wi, hi := w.window.GetSize()
@ -246,14 +246,14 @@ func (w *Window) Size() (width, height float64) {
return width, height
}
// Show makes a window visible if it was hidden.
// Show makes the Window visible if it was hidden.
func (w *Window) Show() {
mainthread.Call(func() {
w.window.Show()
})
}
// Hide hides a window if it was visible.
// Hide hides the Window if it was visible.
func (w *Window) Hide() {
mainthread.Call(func() {
w.window.Hide()
@ -291,11 +291,11 @@ func (w *Window) setWindowed() {
})
}
// SetMonitor sets a window fullscreen on a given monitor. If the monitor is nil, the window
// will be resored to windowed instead.
// SetMonitor sets the Window fullscreen on the given Monitor. If the Monitor is nil, the Window
// will be resored 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
// 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.
func (w *Window) SetMonitor(monitor *Monitor) {
if w.Monitor() != monitor {
@ -307,12 +307,12 @@ func (w *Window) SetMonitor(monitor *Monitor) {
}
}
// IsFullscreen returns true if the window is in the fullscreen mode.
// IsFullscreen returns true if the Window is in fullscreen mode.
func (w *Window) IsFullscreen() bool {
return w.Monitor() != nil
}
// Monitor returns a monitor a fullscreen window is on. If the window is not fullscreen, this
// Monitor returns a monitor the Window is fullscreen is on. If the Window is not fullscreen, this
// function returns nil.
func (w *Window) Monitor() *Monitor {
monitor := mainthread.CallVal(func() interface{} {
@ -326,28 +326,28 @@ func (w *Window) Monitor() *Monitor {
}
}
// Focus brings a window to the front and sets input focus.
// Focus brings the Window to the front and sets input focus.
func (w *Window) Focus() {
mainthread.Call(func() {
w.window.Focus()
})
}
// Focused returns true if a window has input focus.
// Focused returns true if the Window has input focus.
func (w *Window) Focused() bool {
return mainthread.CallVal(func() interface{} {
return w.window.GetAttrib(glfw.Focused) == glfw.True
}).(bool)
}
// Maximize puts a windowed window to a maximized state.
// Maximize puts the Window window to the maximized state.
func (w *Window) Maximize() {
mainthread.Call(func() {
w.window.Maximize()
})
}
// Restore restores a windowed window from a maximized state.
// Restore restores the Window window from the maximized state.
func (w *Window) Restore() {
mainthread.Call(func() {
w.window.Restore()
@ -365,7 +365,7 @@ func (w *Window) begin() {
// Note: must be called inside the main thread.
func (w *Window) end() {
// nothing really
// nothing, really
}
// MakeTriangles generates a specialized copy of the supplied triangles that will draw onto this
@ -376,7 +376,7 @@ func (w *Window) MakeTriangles(t Triangles) Triangles {
return w.canvas.MakeTriangles(t)
}
// SetPicture sets a Picture that will be used in subsequent drawings onto the window.
// SetPicture sets a Picture that will be used in subsequent drawings onto the Window.
func (w *Window) SetPicture(p *Picture) {
w.canvas.SetPicture(p)
}