doc: Improve comments

This commit is contained in:
Hajime Hoshi 2017-10-01 01:59:34 +09:00
parent 23123eb3c0
commit a7fc463d91
10 changed files with 174 additions and 178 deletions

View File

@ -23,7 +23,7 @@ const ColorMDim = affine.ColorMDim
// A ColorM represents a matrix to transform coloring when rendering an image.
//
// A ColorM is applied to the source alpha color
// A ColorM is applied to the straight alpha color
// while an Image's pixels' format is alpha premultiplied.
// Before applying a matrix, a color is un-multiplied, and after applying the matrix,
// the color is multiplied again.
@ -61,8 +61,9 @@ func (c *ColorM) Translate(r, g, b, a float64) {
}
// RotateHue rotates the hue.
// theta represents rotating angle in radian.
func (c *ColorM) RotateHue(theta float64) {
c.impl.RotateHue(theta)
c.ChangeHSV(theta, 1, 1)
}
// ChangeHSV changes HSV (Hue-Saturation-Value) values.
@ -81,13 +82,15 @@ func (c *ColorM) Element(i, j int) float64 {
}
// SetElement sets an element at (i, j).
func (c *ColorM) SetElement(i, j int, value float64) {
c.impl.SetElement(i, j, value)
func (c *ColorM) SetElement(i, j int, element float64) {
c.impl.SetElement(i, j, element)
}
// Monochrome returns a color matrix to make an image monochrome.
// Monochrome is deprecated as of 1.6.0-alpha. Use ChangeHSV(0, 0, 1) instead.
func Monochrome() ColorM {
return ColorM{affine.Monochrome()}
c := ColorM{}
c.ChangeHSV(0, 0, 1)
return c
}
// ScaleColor is deprecated as of 1.2.0-alpha. Use Scale instead.

View File

@ -23,37 +23,37 @@ type GamepadButton int
// GamepadButtons
const (
GamepadButton0 = GamepadButton(ui.GamepadButton0)
GamepadButton1 = GamepadButton(ui.GamepadButton1)
GamepadButton2 = GamepadButton(ui.GamepadButton2)
GamepadButton3 = GamepadButton(ui.GamepadButton3)
GamepadButton4 = GamepadButton(ui.GamepadButton4)
GamepadButton5 = GamepadButton(ui.GamepadButton5)
GamepadButton6 = GamepadButton(ui.GamepadButton6)
GamepadButton7 = GamepadButton(ui.GamepadButton7)
GamepadButton8 = GamepadButton(ui.GamepadButton8)
GamepadButton9 = GamepadButton(ui.GamepadButton9)
GamepadButton10 = GamepadButton(ui.GamepadButton10)
GamepadButton11 = GamepadButton(ui.GamepadButton11)
GamepadButton12 = GamepadButton(ui.GamepadButton12)
GamepadButton13 = GamepadButton(ui.GamepadButton13)
GamepadButton14 = GamepadButton(ui.GamepadButton14)
GamepadButton15 = GamepadButton(ui.GamepadButton15)
GamepadButton16 = GamepadButton(ui.GamepadButton16)
GamepadButton17 = GamepadButton(ui.GamepadButton17)
GamepadButton18 = GamepadButton(ui.GamepadButton18)
GamepadButton19 = GamepadButton(ui.GamepadButton19)
GamepadButton20 = GamepadButton(ui.GamepadButton20)
GamepadButton21 = GamepadButton(ui.GamepadButton21)
GamepadButton22 = GamepadButton(ui.GamepadButton22)
GamepadButton23 = GamepadButton(ui.GamepadButton23)
GamepadButton24 = GamepadButton(ui.GamepadButton24)
GamepadButton25 = GamepadButton(ui.GamepadButton25)
GamepadButton26 = GamepadButton(ui.GamepadButton26)
GamepadButton27 = GamepadButton(ui.GamepadButton27)
GamepadButton28 = GamepadButton(ui.GamepadButton28)
GamepadButton29 = GamepadButton(ui.GamepadButton29)
GamepadButton30 = GamepadButton(ui.GamepadButton30)
GamepadButton31 = GamepadButton(ui.GamepadButton31)
GamepadButtonMax = GamepadButton31
GamepadButton0 GamepadButton = GamepadButton(ui.GamepadButton0)
GamepadButton1 GamepadButton = GamepadButton(ui.GamepadButton1)
GamepadButton2 GamepadButton = GamepadButton(ui.GamepadButton2)
GamepadButton3 GamepadButton = GamepadButton(ui.GamepadButton3)
GamepadButton4 GamepadButton = GamepadButton(ui.GamepadButton4)
GamepadButton5 GamepadButton = GamepadButton(ui.GamepadButton5)
GamepadButton6 GamepadButton = GamepadButton(ui.GamepadButton6)
GamepadButton7 GamepadButton = GamepadButton(ui.GamepadButton7)
GamepadButton8 GamepadButton = GamepadButton(ui.GamepadButton8)
GamepadButton9 GamepadButton = GamepadButton(ui.GamepadButton9)
GamepadButton10 GamepadButton = GamepadButton(ui.GamepadButton10)
GamepadButton11 GamepadButton = GamepadButton(ui.GamepadButton11)
GamepadButton12 GamepadButton = GamepadButton(ui.GamepadButton12)
GamepadButton13 GamepadButton = GamepadButton(ui.GamepadButton13)
GamepadButton14 GamepadButton = GamepadButton(ui.GamepadButton14)
GamepadButton15 GamepadButton = GamepadButton(ui.GamepadButton15)
GamepadButton16 GamepadButton = GamepadButton(ui.GamepadButton16)
GamepadButton17 GamepadButton = GamepadButton(ui.GamepadButton17)
GamepadButton18 GamepadButton = GamepadButton(ui.GamepadButton18)
GamepadButton19 GamepadButton = GamepadButton(ui.GamepadButton19)
GamepadButton20 GamepadButton = GamepadButton(ui.GamepadButton20)
GamepadButton21 GamepadButton = GamepadButton(ui.GamepadButton21)
GamepadButton22 GamepadButton = GamepadButton(ui.GamepadButton22)
GamepadButton23 GamepadButton = GamepadButton(ui.GamepadButton23)
GamepadButton24 GamepadButton = GamepadButton(ui.GamepadButton24)
GamepadButton25 GamepadButton = GamepadButton(ui.GamepadButton25)
GamepadButton26 GamepadButton = GamepadButton(ui.GamepadButton26)
GamepadButton27 GamepadButton = GamepadButton(ui.GamepadButton27)
GamepadButton28 GamepadButton = GamepadButton(ui.GamepadButton28)
GamepadButton29 GamepadButton = GamepadButton(ui.GamepadButton29)
GamepadButton30 GamepadButton = GamepadButton(ui.GamepadButton30)
GamepadButton31 GamepadButton = GamepadButton(ui.GamepadButton31)
GamepadButtonMax GamepadButton = GamepadButton31
)

View File

@ -147,8 +147,8 @@ type Key int
// Keys
const (
{{range $index, $name := .KeyNames}}Key{{$name}} = Key(ui.Key{{$name}})
{{end}} KeyMax = Key{{.LastKeyName}}
{{range $index, $name := .KeyNames}}Key{{$name}} Key = Key(ui.Key{{$name}})
{{end}} KeyMax Key = Key{{.LastKeyName}}
)
`

View File

@ -34,7 +34,7 @@ func (g *GeoM) Reset() {
}
// Apply pre-multiplies a vector (x, y, 1) by the matrix.
// In other words, Apply calculates GeoM * (x, y, 1).
// In other words, Apply calculates GeoM * (x, y, 1)^T.
// The return value is x and y values of the result vector.
func (g *GeoM) Apply(x, y float64) (x2, y2 float64) {
return g.impl.Apply(x, y)
@ -84,6 +84,7 @@ func (g *GeoM) Translate(tx, ty float64) {
}
// Rotate rotates the matrix by theta.
// The unit is radian.
func (g *GeoM) Rotate(theta float64) {
g.impl.Rotate(theta)
}

View File

@ -60,17 +60,11 @@ func (i *Image) Fill(clr color.Color) error {
return nil
}
// DrawImage draws the given image on the receiver image.
// DrawImage draws the given image on the image i.
//
// This method accepts the options.
// The parts of the given image at the parts of the destination.
// After determining parts to draw, this applies the geometry matrix and the color matrix.
// DrawImage accepts the options. For details, see the document of DrawImageOptions.
//
// Here are the default values:
// SourceRect: nil. When SourceRect is nil, the whole source image is used.
// GeoM: Identity matrix
// ColorM: Identity matrix (that changes no colors)
// CompositeMode: CompositeModeSourceOver (regular alpha blending)
// DrawImage determinines the part to draw, then DrawImage applies the geometry matrix and the color matrix.
//
// For drawing, the pixels of the argument image at the time of this call is adopted.
// Even if the argument image is mutated after this call,
@ -156,9 +150,11 @@ func (i *Image) ColorModel() color.Model {
// At returns the color of the image at (x, y).
//
// This method loads pixels from GPU to system memory if necessary.
// At loads pixels from GPU to system memory if necessary, which means that At can be slow.
//
// This method can't be called before the main loop (ebiten.Run) starts (as of version 1.4.0-alpha).
// At always returns color.Transparend if the image is disposed.
//
// At can't be called before the main loop (ebiten.Run) starts (as of version 1.4.0-alpha).
func (i *Image) At(x, y int) color.Color {
if i.restorable == nil {
return color.Transparent
@ -171,10 +167,9 @@ func (i *Image) At(x, y int) color.Color {
return clr
}
// Dispose disposes the image data. After disposing, the image becomes invalid.
// This is useful to save memory.
// Dispose disposes the image data. After disposing, most of image functions do nothing and returns meaningless values.
//
// The behavior of any functions for a disposed image is undefined.
// Dispose is useful to save memory.
//
// When the image is disposed, Dipose does nothing.
//
@ -219,9 +214,20 @@ func (i *Image) ReplacePixels(p []uint8) error {
// A DrawImageOptions represents options to render an image on an image.
type DrawImageOptions struct {
SourceRect *image.Rectangle
GeoM GeoM
ColorM ColorM
// SourceRect is the region of the source image to draw.
// If SourceRect is nil, whole image is used.
SourceRect *image.Rectangle
// GeoM is a geometry matrix to draw.
// The default (zero) value is identify, which draws the image at (0, 0).
GeoM GeoM
// ColorM is a color matrix to draw.
// The default (zero) value is identity, which doesn't change any color.
ColorM ColorM
// CompositeMode is a composite mode to draw.
// The default (zero) value is regular alpha blending.
CompositeMode CompositeMode
// Deprecated (as of 1.5.0-alpha): Use SourceRect instead.

View File

@ -23,7 +23,7 @@ import (
// InputChars represents the environment's locale-dependent translation of keyboard
// input to Unicode characters.
//
// IsKeyPressed is based on a mapping of device codes to input device keys.
// IsKeyPressed is based on a mapping of device (US keyboard) codes to input device keys.
// "Control" and modifier keys should be handled with IsKeyPressed.
//
// This function is concurrent-safe.
@ -56,46 +56,42 @@ func IsMouseButtonPressed(mouseButton MouseButton) bool {
return ui.CurrentInput().IsMouseButtonPressed(ui.MouseButton(mouseButton))
}
// GamepadAxisNum returns the number of axes of the gamepad.
// GamepadAxisNum returns the number of axes of the gamepad (id).
//
// This function is concurrent-safe.
//
// NOTE: Gamepad API is available only on desktops, Chrome and Firefox.
// To use this API, browsers might require rebooting the browser.
func GamepadAxisNum(id int) int {
return ui.CurrentInput().GamepadAxisNum(id)
}
// GamepadAxis returns the float value [-1.0 - 1.0] of the axis.
// GamepadAxis returns the float value [-1.0 - 1.0] of the given gamepad (id)'s axis (axis).
//
// This function is concurrent-safe.
//
// NOTE: Gamepad API is available only on desktops, Chrome and Firefox.
// To use this API, browsers might require rebooting the browser.
func GamepadAxis(id int, axis int) float64 {
return ui.CurrentInput().GamepadAxis(id, axis)
}
// GamepadButtonNum returns the number of the buttons of the gamepad.
// GamepadButtonNum returns the number of the buttons of the given gamepad (id).
//
// This function is concurrent-safe.
//
// NOTE: Gamepad API is available only on desktops, Chrome and Firefox.
// To use this API, browsers might require rebooting the browser.
func GamepadButtonNum(id int) int {
return ui.CurrentInput().GamepadButtonNum(id)
}
// IsGamepadButtonPressed returns the boolean indicating the buttons is pressed or not.
// IsGamepadButtonPressed returns the boolean indicating the given button of the gamepad (id) is pressed or not.
//
// This function is concurrent-safe.
//
// The key states vary depending on environments.
// The button states vary depending on environments.
// There can be differences even between Chrome and Firefox.
// Don't assume that states of a keys are always same when same buttons are pressed.
// Don't assume that returned values are always same when same buttons are pressed.
//
// NOTE: Gamepad API is available only on desktops, Chrome and Firefox.
// To use this API, browsers might require rebooting the browser.
func IsGamepadButtonPressed(id int, button GamepadButton) bool {
return ui.CurrentInput().IsGamepadButtonPressed(id, ui.GamepadButton(button))
}

View File

@ -149,11 +149,6 @@ func (c *ColorM) Translate(r, g, b, a float64) {
c.elements = es
}
// RotateHue rotates the hue.
func (c *ColorM) RotateHue(theta float64) {
c.ChangeHSV(theta, 1, 1)
}
var (
// The YCbCr value ranges are:
// Y: [ 0 - 1 ]
@ -200,14 +195,3 @@ func (c *ColorM) ChangeHSV(hueTheta float64, saturationScale float64, valueScale
c.Scale(v, s*v, s*v, 1)
c.Concat(&yCbCrToRgb)
}
var monochrome ColorM
func init() {
monochrome.ChangeHSV(0, 0, 1)
}
// Monochrome returns a color matrix to make an image monochrome.
func Monochrome() ColorM {
return monochrome
}

158
keys.go
View File

@ -27,83 +27,83 @@ type Key int
// Keys
const (
Key0 = Key(ui.Key0)
Key1 = Key(ui.Key1)
Key2 = Key(ui.Key2)
Key3 = Key(ui.Key3)
Key4 = Key(ui.Key4)
Key5 = Key(ui.Key5)
Key6 = Key(ui.Key6)
Key7 = Key(ui.Key7)
Key8 = Key(ui.Key8)
Key9 = Key(ui.Key9)
KeyA = Key(ui.KeyA)
KeyB = Key(ui.KeyB)
KeyC = Key(ui.KeyC)
KeyD = Key(ui.KeyD)
KeyE = Key(ui.KeyE)
KeyF = Key(ui.KeyF)
KeyG = Key(ui.KeyG)
KeyH = Key(ui.KeyH)
KeyI = Key(ui.KeyI)
KeyJ = Key(ui.KeyJ)
KeyK = Key(ui.KeyK)
KeyL = Key(ui.KeyL)
KeyM = Key(ui.KeyM)
KeyN = Key(ui.KeyN)
KeyO = Key(ui.KeyO)
KeyP = Key(ui.KeyP)
KeyQ = Key(ui.KeyQ)
KeyR = Key(ui.KeyR)
KeyS = Key(ui.KeyS)
KeyT = Key(ui.KeyT)
KeyU = Key(ui.KeyU)
KeyV = Key(ui.KeyV)
KeyW = Key(ui.KeyW)
KeyX = Key(ui.KeyX)
KeyY = Key(ui.KeyY)
KeyZ = Key(ui.KeyZ)
KeyAlt = Key(ui.KeyAlt)
KeyApostrophe = Key(ui.KeyApostrophe)
KeyBackslash = Key(ui.KeyBackslash)
KeyBackspace = Key(ui.KeyBackspace)
KeyCapsLock = Key(ui.KeyCapsLock)
KeyComma = Key(ui.KeyComma)
KeyControl = Key(ui.KeyControl)
KeyDelete = Key(ui.KeyDelete)
KeyDown = Key(ui.KeyDown)
KeyEnd = Key(ui.KeyEnd)
KeyEnter = Key(ui.KeyEnter)
KeyEqual = Key(ui.KeyEqual)
KeyEscape = Key(ui.KeyEscape)
KeyF1 = Key(ui.KeyF1)
KeyF2 = Key(ui.KeyF2)
KeyF3 = Key(ui.KeyF3)
KeyF4 = Key(ui.KeyF4)
KeyF5 = Key(ui.KeyF5)
KeyF6 = Key(ui.KeyF6)
KeyF7 = Key(ui.KeyF7)
KeyF8 = Key(ui.KeyF8)
KeyF9 = Key(ui.KeyF9)
KeyF10 = Key(ui.KeyF10)
KeyF11 = Key(ui.KeyF11)
KeyF12 = Key(ui.KeyF12)
KeyGraveAccent = Key(ui.KeyGraveAccent)
KeyHome = Key(ui.KeyHome)
KeyInsert = Key(ui.KeyInsert)
KeyLeft = Key(ui.KeyLeft)
KeyLeftBracket = Key(ui.KeyLeftBracket)
KeyMinus = Key(ui.KeyMinus)
KeyPageDown = Key(ui.KeyPageDown)
KeyPageUp = Key(ui.KeyPageUp)
KeyPeriod = Key(ui.KeyPeriod)
KeyRight = Key(ui.KeyRight)
KeyRightBracket = Key(ui.KeyRightBracket)
KeySemicolon = Key(ui.KeySemicolon)
KeyShift = Key(ui.KeyShift)
KeySlash = Key(ui.KeySlash)
KeySpace = Key(ui.KeySpace)
KeyTab = Key(ui.KeyTab)
KeyUp = Key(ui.KeyUp)
KeyMax = KeyUp
Key0 Key = Key(ui.Key0)
Key1 Key = Key(ui.Key1)
Key2 Key = Key(ui.Key2)
Key3 Key = Key(ui.Key3)
Key4 Key = Key(ui.Key4)
Key5 Key = Key(ui.Key5)
Key6 Key = Key(ui.Key6)
Key7 Key = Key(ui.Key7)
Key8 Key = Key(ui.Key8)
Key9 Key = Key(ui.Key9)
KeyA Key = Key(ui.KeyA)
KeyB Key = Key(ui.KeyB)
KeyC Key = Key(ui.KeyC)
KeyD Key = Key(ui.KeyD)
KeyE Key = Key(ui.KeyE)
KeyF Key = Key(ui.KeyF)
KeyG Key = Key(ui.KeyG)
KeyH Key = Key(ui.KeyH)
KeyI Key = Key(ui.KeyI)
KeyJ Key = Key(ui.KeyJ)
KeyK Key = Key(ui.KeyK)
KeyL Key = Key(ui.KeyL)
KeyM Key = Key(ui.KeyM)
KeyN Key = Key(ui.KeyN)
KeyO Key = Key(ui.KeyO)
KeyP Key = Key(ui.KeyP)
KeyQ Key = Key(ui.KeyQ)
KeyR Key = Key(ui.KeyR)
KeyS Key = Key(ui.KeyS)
KeyT Key = Key(ui.KeyT)
KeyU Key = Key(ui.KeyU)
KeyV Key = Key(ui.KeyV)
KeyW Key = Key(ui.KeyW)
KeyX Key = Key(ui.KeyX)
KeyY Key = Key(ui.KeyY)
KeyZ Key = Key(ui.KeyZ)
KeyAlt Key = Key(ui.KeyAlt)
KeyApostrophe Key = Key(ui.KeyApostrophe)
KeyBackslash Key = Key(ui.KeyBackslash)
KeyBackspace Key = Key(ui.KeyBackspace)
KeyCapsLock Key = Key(ui.KeyCapsLock)
KeyComma Key = Key(ui.KeyComma)
KeyControl Key = Key(ui.KeyControl)
KeyDelete Key = Key(ui.KeyDelete)
KeyDown Key = Key(ui.KeyDown)
KeyEnd Key = Key(ui.KeyEnd)
KeyEnter Key = Key(ui.KeyEnter)
KeyEqual Key = Key(ui.KeyEqual)
KeyEscape Key = Key(ui.KeyEscape)
KeyF1 Key = Key(ui.KeyF1)
KeyF2 Key = Key(ui.KeyF2)
KeyF3 Key = Key(ui.KeyF3)
KeyF4 Key = Key(ui.KeyF4)
KeyF5 Key = Key(ui.KeyF5)
KeyF6 Key = Key(ui.KeyF6)
KeyF7 Key = Key(ui.KeyF7)
KeyF8 Key = Key(ui.KeyF8)
KeyF9 Key = Key(ui.KeyF9)
KeyF10 Key = Key(ui.KeyF10)
KeyF11 Key = Key(ui.KeyF11)
KeyF12 Key = Key(ui.KeyF12)
KeyGraveAccent Key = Key(ui.KeyGraveAccent)
KeyHome Key = Key(ui.KeyHome)
KeyInsert Key = Key(ui.KeyInsert)
KeyLeft Key = Key(ui.KeyLeft)
KeyLeftBracket Key = Key(ui.KeyLeftBracket)
KeyMinus Key = Key(ui.KeyMinus)
KeyPageDown Key = Key(ui.KeyPageDown)
KeyPageUp Key = Key(ui.KeyPageUp)
KeyPeriod Key = Key(ui.KeyPeriod)
KeyRight Key = Key(ui.KeyRight)
KeyRightBracket Key = Key(ui.KeyRightBracket)
KeySemicolon Key = Key(ui.KeySemicolon)
KeyShift Key = Key(ui.KeyShift)
KeySlash Key = Key(ui.KeySlash)
KeySpace Key = Key(ui.KeySpace)
KeyTab Key = Key(ui.KeyTab)
KeyUp Key = Key(ui.KeyUp)
KeyMax Key = KeyUp
)

View File

@ -23,7 +23,7 @@ type MouseButton int
// MouseButtons
const (
MouseButtonLeft = MouseButton(ui.MouseButtonLeft)
MouseButtonRight = MouseButton(ui.MouseButtonRight)
MouseButtonMiddle = MouseButton(ui.MouseButtonMiddle)
MouseButtonLeft MouseButton = MouseButton(ui.MouseButtonLeft)
MouseButtonRight MouseButton = MouseButton(ui.MouseButtonRight)
MouseButtonMiddle MouseButton = MouseButton(ui.MouseButtonMiddle)
)

26
run.go
View File

@ -27,12 +27,11 @@ const FPS = clock.FPS
// CurrentFPS returns the current number of frames per second of rendering.
//
// This function is concurrent-safe.
//
// This value represents how many times rendering happens in a second and
// The returned value represents how many times rendering happens in a second and
// NOT how many times logical game updating (a passed function to Run) happens.
// Note that logical game updating is assured to happen 60 times in a second
// as long as the screen is active.
// Note that logical game updating is assured to happen 60 times in a second.
//
// This function is concurrent-safe.
func CurrentFPS() float64 {
return clock.CurrentFPS()
}
@ -93,13 +92,18 @@ func (u *updater) Invalidate() {
// Run runs the game.
// f is a function which is called at every frame.
// The argument (*Image) is the render target that represents the screen.
// The screen size is based on the given values (width and height).
//
// Run must be called from the main thread.
// Note that ebiten bounds the main goroutine to the main OS thread by runtime.LockOSThread.
// A window size is based on the given values (width, height and scale).
// scale is used to enlarge the screen.
//
// Run must be called from the OS main thread.
// Note that Ebiten bounds the main goroutine to the main OS thread by runtime.LockOSThread.
//
// The given function f is guaranteed to be called 60 times a second
// even if a rendering frame is skipped.
// f is not called when the screen is not shown.
// f is not called when the window is in background by default.
// This setting is configurable with SetRunnableInBackground.
//
// The given scale is ignored on fullscreen mode.
//
@ -107,6 +111,8 @@ func (u *updater) Invalidate() {
// In the case of 2), Run returns the same error.
//
// The size unit is device-independent pixel.
//
// Don't call Run twice or more in one process.
func Run(f func(*Image) error, width, height int, scale float64, title string) error {
ch := make(chan error)
go func() {
@ -131,8 +137,6 @@ func Run(f func(*Image) error, width, height int, scale float64, title string) e
//
// Typically, Ebiten users don't have to call this directly.
// Instead, functions in github.com/hajimehoshi/ebiten/mobile module call this.
//
// The size unit is device-independent pixel.
func RunWithoutMainLoop(f func(*Image) error, width, height int, scale float64, title string) <-chan error {
ch := make(chan error)
go func() {
@ -202,6 +206,8 @@ func SetCursorVisibility(visible bool) {
// IsFullscreen returns a boolean value indicating whether
// the current mode is fullscreen or not.
//
// IsFullscreen always returns false on mobiles.
//
// This function is concurrent-safe.
func IsFullscreen() bool {
return ui.IsFullscreen()