inpututil: add comments about Update

All the inpututil functions treating durations must be called Update,
or users cannot get correct results.

This is really a bad designed API, and we should revisit this later.

Closes #2462

inpututil/inpututil.go

@@ -91,7 +91,7 @@ func (i *inputState) update() {
 	defer i.m.Unlock()
 
 	// Keyboard
-	copy(i.prevKeyDurations[:], i.keyDurations[:])
+	copy(i.prevKeyDurations, i.keyDurations)
 	for k := ebiten.Key(0); k <= ebiten.KeyMax; k++ {
 		if ebiten.IsKeyPressed(k) {
 			i.keyDurations[k]++
@@ -216,6 +216,8 @@ func (i *inputState) update() {
 // AppendPressedKeys append currently pressed keyboard keys to keys and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendPressedKeys must be called in a game's Update, not Draw.
+//
 // AppendPressedKeys is concurrent safe.
 func AppendPressedKeys(keys []ebiten.Key) []ebiten.Key {
 	theInputState.m.RLock()
@@ -232,6 +234,8 @@ func AppendPressedKeys(keys []ebiten.Key) []ebiten.Key {
 
 // PressedKeys returns a set of currently pressed keyboard keys.
 //
+// PressedKeys must be called in a game's Update, not Draw.
+//
 // Deprecated: as of v2.2. Use AppendPressedKeys instead.
 func PressedKeys() []ebiten.Key {
 	return AppendPressedKeys(nil)
@@ -240,6 +244,8 @@ func PressedKeys() []ebiten.Key {
 // AppendJustPressedKeys append just pressed keyboard keys to keys and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustPressedKeys must be called in a game's Update, not Draw.
+//
 // AppendJustPressedKeys is concurrent safe.
 func AppendJustPressedKeys(keys []ebiten.Key) []ebiten.Key {
 	theInputState.m.RLock()
@@ -257,6 +263,8 @@ func AppendJustPressedKeys(keys []ebiten.Key) []ebiten.Key {
 // AppendJustReleasedKeys append just released keyboard keys to keys and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustReleasedKeys must be called in a game's Update, not Draw.
+//
 // AppendJustReleasedKeys is concurrent safe.
 func AppendJustReleasedKeys(keys []ebiten.Key) []ebiten.Key {
 	theInputState.m.RLock()
@@ -277,6 +285,8 @@ func AppendJustReleasedKeys(keys []ebiten.Key) []ebiten.Key {
 // IsKeyJustPressed returns a boolean value indicating
 // whether the given key is pressed just in the current tick.
 //
+// IsKeyJustPressed must be called in a game's Update, not Draw.
+//
 // IsKeyJustPressed is concurrent safe.
 func IsKeyJustPressed(key ebiten.Key) bool {
 	return KeyPressDuration(key) == 1
@@ -285,6 +295,8 @@ func IsKeyJustPressed(key ebiten.Key) bool {
 // IsKeyJustReleased returns a boolean value indicating
 // whether the given key is released just in the current tick.
 //
+// IsKeyJustReleased must be called in a game's Update, not Draw.
+//
 // IsKeyJustReleased is concurrent safe.
 func IsKeyJustReleased(key ebiten.Key) bool {
 	theInputState.m.RLock()
@@ -295,6 +307,8 @@ func IsKeyJustReleased(key ebiten.Key) bool {
 
 // KeyPressDuration returns how long the key is pressed in ticks (Update).
 //
+// KeyPressDuration must be called in a game's Update, not Draw.
+//
 // KeyPressDuration is concurrent safe.
 func KeyPressDuration(key ebiten.Key) int {
 	theInputState.m.RLock()
@@ -306,6 +320,8 @@ func KeyPressDuration(key ebiten.Key) int {
 // IsMouseButtonJustPressed returns a boolean value indicating
 // whether the given mouse button is pressed just in the current tick.
 //
+// IsMouseButtonJustPressed must be called in a game's Update, not Draw.
+//
 // IsMouseButtonJustPressed is concurrent safe.
 func IsMouseButtonJustPressed(button ebiten.MouseButton) bool {
 	return MouseButtonPressDuration(button) == 1
@@ -314,6 +330,8 @@ func IsMouseButtonJustPressed(button ebiten.MouseButton) bool {
 // IsMouseButtonJustReleased returns a boolean value indicating
 // whether the given mouse button is released just in the current tick.
 //
+// IsMouseButtonJustReleased must be called in a game's Update, not Draw.
+//
 // IsMouseButtonJustReleased is concurrent safe.
 func IsMouseButtonJustReleased(button ebiten.MouseButton) bool {
 	theInputState.m.RLock()
@@ -325,6 +343,8 @@ func IsMouseButtonJustReleased(button ebiten.MouseButton) bool {
 
 // MouseButtonPressDuration returns how long the mouse button is pressed in ticks (Update).
 //
+// MouseButtonPressDuration must be called in a game's Update, not Draw.
+//
 // MouseButtonPressDuration is concurrent safe.
 func MouseButtonPressDuration(button ebiten.MouseButton) int {
 	theInputState.m.RLock()
@@ -337,6 +357,8 @@ func MouseButtonPressDuration(button ebiten.MouseButton) int {
 // and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustConnectedGamepadIDs must be called in a game's Update, not Draw.
+//
 // AppendJustConnectedGamepadIDs is concurrent safe.
 func AppendJustConnectedGamepadIDs(gamepadIDs []ebiten.GamepadID) []ebiten.GamepadID {
 	origLen := len(gamepadIDs)
@@ -356,6 +378,8 @@ func AppendJustConnectedGamepadIDs(gamepadIDs []ebiten.GamepadID) []ebiten.Gamep
 
 // JustConnectedGamepadIDs returns gamepad IDs that are connected just in the current tick.
 //
+// JustConnectedGamepadIDs must be called in a game's Update, not Draw.
+//
 // Deprecated: as of v2.2. Use AppendJustConnectedGamepadIDs instead.
 func JustConnectedGamepadIDs() []ebiten.GamepadID {
 	return AppendJustConnectedGamepadIDs(nil)
@@ -364,6 +388,8 @@ func JustConnectedGamepadIDs() []ebiten.GamepadID {
 // IsGamepadJustDisconnected returns a boolean value indicating
 // whether the gamepad of the given id is released just in the current tick.
 //
+// IsGamepadJustDisconnected must be called in a game's Update, not Draw.
+//
 // IsGamepadJustDisconnected is concurrent safe.
 func IsGamepadJustDisconnected(id ebiten.GamepadID) bool {
 	theInputState.m.RLock()
@@ -376,6 +402,8 @@ func IsGamepadJustDisconnected(id ebiten.GamepadID) bool {
 // AppendPressedGamepadButtons append currently pressed gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendPressedGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendPressedGamepadButtons is concurrent safe.
 func AppendPressedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.GamepadButton) []ebiten.GamepadButton {
 	theInputState.m.RLock()
@@ -398,6 +426,8 @@ func AppendPressedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.GamepadBu
 // AppendJustPressedGamepadButtons append just pressed gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustPressedGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendJustPressedGamepadButtons is concurrent safe.
 func AppendJustPressedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.GamepadButton) []ebiten.GamepadButton {
 	theInputState.m.RLock()
@@ -420,6 +450,8 @@ func AppendJustPressedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.Gamep
 // AppendJustReleasedGamepadButtons append just released gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustReleasedGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendJustReleasedGamepadButtons is concurrent safe.
 func AppendJustReleasedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.GamepadButton) []ebiten.GamepadButton {
 	theInputState.m.RLock()
@@ -450,6 +482,8 @@ func AppendJustReleasedGamepadButtons(id ebiten.GamepadID, buttons []ebiten.Game
 // IsGamepadButtonJustPressed returns a boolean value indicating
 // whether the given gamepad button of the gamepad id is pressed just in the current tick.
 //
+// IsGamepadButtonJustPressed must be called in a game's Update, not Draw.
+//
 // IsGamepadButtonJustPressed is concurrent safe.
 func IsGamepadButtonJustPressed(id ebiten.GamepadID, button ebiten.GamepadButton) bool {
 	return GamepadButtonPressDuration(id, button) == 1
@@ -458,6 +492,8 @@ func IsGamepadButtonJustPressed(id ebiten.GamepadID, button ebiten.GamepadButton
 // IsGamepadButtonJustReleased returns a boolean value indicating
 // whether the given gamepad button of the gamepad id is released just in the current tick.
 //
+// IsGamepadButtonJustReleased must be called in a game's Update, not Draw.
+//
 // IsGamepadButtonJustReleased is concurrent safe.
 func IsGamepadButtonJustReleased(id ebiten.GamepadID, button ebiten.GamepadButton) bool {
 	theInputState.m.RLock()
@@ -475,6 +511,8 @@ func IsGamepadButtonJustReleased(id ebiten.GamepadID, button ebiten.GamepadButto
 
 // GamepadButtonPressDuration returns how long the gamepad button of the gamepad id is pressed in ticks (Update).
 //
+// GamepadButtonPressDuration must be called in a game's Update, not Draw.
+//
 // GamepadButtonPressDuration is concurrent safe.
 func GamepadButtonPressDuration(id ebiten.GamepadID, button ebiten.GamepadButton) int {
 	theInputState.m.RLock()
@@ -489,6 +527,8 @@ func GamepadButtonPressDuration(id ebiten.GamepadID, button ebiten.GamepadButton
 // AppendPressedStandardGamepadButtons append currently pressed standard gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendPressedStandardGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendPressedStandardGamepadButtons is concurrent safe.
 func AppendPressedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebiten.StandardGamepadButton) []ebiten.StandardGamepadButton {
 	theInputState.m.RLock()
@@ -511,6 +551,8 @@ func AppendPressedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebiten.S
 // AppendJustPressedStandardGamepadButtons append just pressed standard gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustPressedStandardGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendJustPressedStandardGamepadButtons is concurrent safe.
 func AppendJustPressedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebiten.StandardGamepadButton) []ebiten.StandardGamepadButton {
 	theInputState.m.RLock()
@@ -533,6 +575,8 @@ func AppendJustPressedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebit
 // AppendJustReleasedStandardGamepadButtons append just released standard gamepad buttons to buttons and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustReleasedStandardGamepadButtons must be called in a game's Update, not Draw.
+//
 // AppendJustReleasedStandardGamepadButtons is concurrent safe.
 func AppendJustReleasedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebiten.StandardGamepadButton) []ebiten.StandardGamepadButton {
 	theInputState.m.RLock()
@@ -563,6 +607,8 @@ func AppendJustReleasedStandardGamepadButtons(id ebiten.GamepadID, buttons []ebi
 // IsStandardGamepadButtonJustPressed returns a boolean value indicating
 // whether the given standard gamepad button of the gamepad id is pressed just in the current tick.
 //
+// IsStandardGamepadButtonJustPressed must be called in a game's Update, not Draw.
+//
 // IsStandardGamepadButtonJustPressed is concurrent safe.
 func IsStandardGamepadButtonJustPressed(id ebiten.GamepadID, button ebiten.StandardGamepadButton) bool {
 	return StandardGamepadButtonPressDuration(id, button) == 1
@@ -571,6 +617,8 @@ func IsStandardGamepadButtonJustPressed(id ebiten.GamepadID, button ebiten.Stand
 // IsStandardGamepadButtonJustReleased returns a boolean value indicating
 // whether the given standard gamepad button of the gamepad id is released just in the current tick.
 //
+// IsStandardGamepadButtonJustReleased must be called in a game's Update, not Draw.
+//
 // IsStandardGamepadButtonJustReleased is concurrent safe.
 func IsStandardGamepadButtonJustReleased(id ebiten.GamepadID, button ebiten.StandardGamepadButton) bool {
 	theInputState.m.RLock()
@@ -589,6 +637,8 @@ func IsStandardGamepadButtonJustReleased(id ebiten.GamepadID, button ebiten.Stan
 
 // StandardGamepadButtonPressDuration returns how long the standard gamepad button of the gamepad id is pressed in ticks (Update).
 //
+// StandardGamepadButtonPressDuration must be called in a game's Update, not Draw.
+//
 // StandardGamepadButtonPressDuration is concurrent safe.
 func StandardGamepadButtonPressDuration(id ebiten.GamepadID, button ebiten.StandardGamepadButton) int {
 	theInputState.m.RLock()
@@ -604,6 +654,8 @@ func StandardGamepadButtonPressDuration(id ebiten.GamepadID, button ebiten.Stand
 // and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustPressedTouchIDs must be called in a game's Update, not Draw.
+//
 // AppendJustPressedTouchIDs is concurrent safe.
 func AppendJustPressedTouchIDs(touchIDs []ebiten.TouchID) []ebiten.TouchID {
 	theInputState.m.RLock()
@@ -626,6 +678,8 @@ func AppendJustPressedTouchIDs(touchIDs []ebiten.TouchID) []ebiten.TouchID {
 
 // JustPressedTouchIDs returns touch IDs that are created just in the current tick.
 //
+// JustPressedTouchIDs must be called in a game's Update, not Draw.
+//
 // Deprecated: as of v2.2. Use AppendJustPressedTouchIDs instead.
 func JustPressedTouchIDs() []ebiten.TouchID {
 	return AppendJustPressedTouchIDs(nil)
@@ -635,6 +689,8 @@ func JustPressedTouchIDs() []ebiten.TouchID {
 // and returns the extended buffer.
 // Giving a slice that already has enough capacity works efficiently.
 //
+// AppendJustReleasedTouchIDs must be called in a game's Update, not Draw.
+//
 // AppendJustReleasedTouchIDs is concurrent safe.
 func AppendJustReleasedTouchIDs(touchIDs []ebiten.TouchID) []ebiten.TouchID {
 	theInputState.m.RLock()
@@ -658,6 +714,8 @@ func AppendJustReleasedTouchIDs(touchIDs []ebiten.TouchID) []ebiten.TouchID {
 // IsTouchJustReleased returns a boolean value indicating
 // whether the given touch is released just in the current tick.
 //
+// IsTouchJustReleased must be called in a game's Update, not Draw.
+//
 // IsTouchJustReleased is concurrent safe.
 func IsTouchJustReleased(id ebiten.TouchID) bool {
 	theInputState.m.RLock()
@@ -668,6 +726,8 @@ func IsTouchJustReleased(id ebiten.TouchID) bool {
 
 // TouchPressDuration returns how long the touch remains in ticks (Update).
 //
+// TouchPressDuration must be called in a game's Update, not Draw.
+//
 // TouchPressDuration is concurrent safe.
 func TouchPressDuration(id ebiten.TouchID) int {
 	theInputState.m.RLock()
@@ -679,6 +739,8 @@ func TouchPressDuration(id ebiten.TouchID) int {
 // TouchPositionInPreviousTick returns the position in the previous tick.
 // If the touch is a just-released touch, TouchPositionInPreviousTick returns the last position of the touch.
 //
+// TouchPositionInPreviousTick must be called in a game's Update, not Draw.
+//
 // TouchJustReleasedPosition is concurrent safe.
 func TouchPositionInPreviousTick(id ebiten.TouchID) (int, int) {
 	theInputState.m.RLock()