ebiten/input.go

398 lines
13 KiB
Go
Raw Normal View History

2015-02-01 13:47:47 +01:00
// Copyright 2015 Hajime Hoshi
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package ebiten
import (
"github.com/hajimehoshi/ebiten/v2/internal/gamepad"
"github.com/hajimehoshi/ebiten/v2/internal/gamepaddb"
"github.com/hajimehoshi/ebiten/v2/internal/ui"
2015-02-01 13:47:47 +01:00
)
// AppendInputChars appends "printable" runes, read from the keyboard at the time update is called, to runes,
// and returns the extended buffer.
// Giving a slice that already has enough capacity works efficiently.
2017-08-14 21:11:51 +02:00
//
// AppendInputChars represents the environment's locale-dependent translation of keyboard
2021-12-19 15:58:55 +01:00
// input to Unicode characters. On the other hand, Key represents a physical key of US keyboard layout
//
// "Control" and modifier keys should be handled with IsKeyPressed.
2017-08-14 21:11:51 +02:00
//
// AppendInputChars is concurrent-safe.
//
// On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.
//
// Keyboards don't work on iOS yet (#1090).
func AppendInputChars(runes []rune) []rune {
return ui.Get().Input().AppendInputChars(runes)
}
// InputChars return "printable" runes read from the keyboard at the time update is called.
//
2021-07-09 20:19:23 +02:00
// Deprecated: as of v2.2. Use AppendInputChars instead.
2017-08-14 21:11:51 +02:00
func InputChars() []rune {
return AppendInputChars(nil)
2017-08-14 21:11:51 +02:00
}
2015-02-01 13:47:47 +01:00
// IsKeyPressed returns a boolean indicating whether key is pressed.
//
// If you want to know whether the key started being pressed in the current frame,
// use inpututil.IsKeyJustPressed
//
2021-12-19 15:58:55 +01:00
// Note that a Key represents a pysical key of US keyboard layout.
// For example, KeyQ represents Q key on US keyboards and ' (quote) key on Dvorak keyboards.
//
2018-04-21 18:39:28 +02:00
// Known issue: On Edge browser, some keys don't work well:
//
// - KeyKPEnter and KeyKPEqual are recognized as KeyEnter and KeyEqual.
// - KeyPrintScreen is only treated at keyup event.
//
// IsKeyPressed is concurrent-safe.
//
// On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.
//
// Keyboards don't work on iOS yet (#1090).
2015-02-01 13:47:47 +01:00
func IsKeyPressed(key Key) bool {
if !key.isValid() {
return false
}
var keys []ui.Key
switch key {
case KeyAlt:
keys = []ui.Key{ui.KeyAltLeft, ui.KeyAltRight}
case KeyControl:
keys = []ui.Key{ui.KeyControlLeft, ui.KeyControlRight}
case KeyShift:
keys = []ui.Key{ui.KeyShiftLeft, ui.KeyShiftRight}
case KeyMeta:
keys = []ui.Key{ui.KeyMetaLeft, ui.KeyMetaRight}
default:
keys = []ui.Key{ui.Key(key)}
}
for _, k := range keys {
if ui.Get().Input().IsKeyPressed(k) {
return true
}
}
return false
2015-02-01 13:47:47 +01:00
}
2019-04-13 05:46:32 +02:00
// CursorPosition returns a position of a mouse cursor relative to the game screen (window). The cursor position is
// 'logical' position and this considers the scale of the screen.
//
// CursorPosition returns (0, 0) before the main loop on desktops and browsers.
//
// CursorPosition always returns (0, 0) on mobiles.
//
// CursorPosition is concurrent-safe.
2015-02-01 13:47:47 +01:00
func CursorPosition() (x, y int) {
return ui.Get().Input().CursorPosition()
2015-02-01 13:47:47 +01:00
}
2021-07-19 18:12:17 +02:00
// Wheel returns x and y offsets of the mouse wheel or touchpad scroll.
2018-06-17 17:38:30 +02:00
// It returns 0 if the wheel isn't being rolled.
2018-10-11 15:36:38 +02:00
//
// Wheel is concurrent-safe.
2018-09-30 10:01:45 +02:00
func Wheel() (xoff, yoff float64) {
return ui.Get().Input().Wheel()
2018-06-17 17:38:30 +02:00
}
2015-02-01 13:47:47 +01:00
// IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.
//
// If you want to know whether the mouseButton started being pressed in the current frame,
// use inpututil.IsMouseButtonJustPressed
//
// IsMouseButtonPressed is concurrent-safe.
2015-02-01 13:47:47 +01:00
func IsMouseButtonPressed(mouseButton MouseButton) bool {
return ui.Get().Input().IsMouseButtonPressed(mouseButton)
2015-02-01 13:47:47 +01:00
}
// GamepadID represents a gamepad's identifier.
type GamepadID = gamepad.ID
// GamepadSDLID returns a string with the GUID generated in the same way as SDL.
// To detect devices, see also the community project of gamepad devices database: https://github.com/gabomdq/SDL_GameControllerDB
//
// GamepadSDLID always returns an empty string on browsers and mobiles.
2020-01-09 15:05:29 +01:00
//
// GamepadSDLID is concurrent-safe.
func GamepadSDLID(id GamepadID) string {
g := gamepad.Get(id)
if g == nil {
return ""
}
return g.SDLID()
}
// GamepadName returns a string with the name.
// This function may vary in how it returns descriptions for the same device across platforms.
// for example the following drivers/platforms see a Xbox One controller as the following:
//
2020-01-09 15:05:29 +01:00
// - Windows: "Xbox Controller"
// - Chrome: "Xbox 360 Controller (XInput STANDARD GAMEPAD)"
// - Firefox: "xinput"
//
2020-01-09 15:05:29 +01:00
// GamepadName is concurrent-safe.
func GamepadName(id GamepadID) string {
g := gamepad.Get(id)
if g == nil {
return ""
}
return g.Name()
}
// AppendGamepadIDs appends available gamepad IDs to gamepadIDs, and returns the extended buffer.
// Giving a slice that already has enough capacity works efficiently.
2017-10-25 19:59:06 +02:00
//
// AppendGamepadIDs is concurrent-safe.
func AppendGamepadIDs(gamepadIDs []GamepadID) []GamepadID {
return gamepad.AppendGamepadIDs(gamepadIDs)
}
// GamepadIDs returns a slice indicating available gamepad IDs.
//
2021-07-09 20:19:23 +02:00
// Deprecated: as of v2.2. Use AppendGamepadIDs instead.
func GamepadIDs() []GamepadID {
return AppendGamepadIDs(nil)
2017-10-25 19:59:06 +02:00
}
// GamepadAxisCount returns the number of axes of the gamepad (id).
2015-02-01 13:47:47 +01:00
//
// GamepadAxisCount is concurrent-safe.
func GamepadAxisCount(id GamepadID) int {
g := gamepad.Get(id)
if g == nil {
return 0
}
return g.AxisCount()
2015-02-01 13:47:47 +01:00
}
// GamepadAxisNum returns the number of axes of the gamepad (id).
//
// Deprecated: as of v2.4. Use GamepadAxisCount instead.
func GamepadAxisNum(id GamepadID) int {
return GamepadAxisCount(id)
}
2021-07-19 18:12:17 +02:00
// GamepadAxisValue returns a float value [-1.0 - 1.0] of the given gamepad (id)'s axis (axis).
//
// GamepadAxisValue is concurrent-safe.
func GamepadAxisValue(id GamepadID, axis int) float64 {
g := gamepad.Get(id)
if g == nil {
return 0
}
return g.Axis(axis)
}
2021-07-19 18:12:17 +02:00
// GamepadAxis returns a float value [-1.0 - 1.0] of the given gamepad (id)'s axis (axis).
//
// Deprecated: as of v2.2. Use GamepadAxisValue instead.
func GamepadAxis(id GamepadID, axis int) float64 {
return GamepadAxisValue(id, axis)
2015-02-01 13:47:47 +01:00
}
// GamepadButtonCount returns the number of the buttons of the given gamepad (id).
2015-02-01 13:47:47 +01:00
//
// GamepadButtonCount is concurrent-safe.
func GamepadButtonCount(id GamepadID) int {
g := gamepad.Get(id)
if g == nil {
return 0
}
// For backward compatibility, hats are treated as buttons in GLFW.
return g.ButtonCount() + g.HatCount()*4
2015-02-01 13:47:47 +01:00
}
// GamepadButtonNum returns the number of the buttons of the given gamepad (id).
//
// Deprecated: as of v2.4. Use GamepadButtonCount instead.
func GamepadButtonNum(id GamepadID) int {
return GamepadButtonCount(id)
}
2021-07-19 18:12:17 +02:00
// IsGamepadButtonPressed reports whether the given button of the gamepad (id) is pressed or not.
2015-02-01 13:47:47 +01:00
//
// If you want to know whether the given button of gamepad (id) started being pressed in the current frame,
// use inpututil.IsGamepadButtonJustPressed
//
// IsGamepadButtonPressed is concurrent-safe.
//
2018-04-29 20:58:04 +02:00
// The relationships between physical buttons and buttion IDs depend on environments.
2016-10-29 11:17:25 +02:00
// There can be differences even between Chrome and Firefox.
func IsGamepadButtonPressed(id GamepadID, button GamepadButton) bool {
g := gamepad.Get(id)
if g == nil {
return false
}
nbuttons := g.ButtonCount()
if int(button) < nbuttons {
return g.Button(int(button))
}
// For backward compatibility, hats are treated as buttons in GLFW.
if hat := (int(button) - nbuttons) / 4; hat < g.HatCount() {
dir := (int(button) - nbuttons) % 4
return g.Hat(hat)&(1<<dir) != 0
}
return false
2015-02-01 13:47:47 +01:00
}
// StandardGamepadAxisValue returns a float value [-1.0 - 1.0] of the given gamepad (id)'s standard axis (axis).
//
// StandardGamepadAxisValue returns 0 when the gamepad doesn't have a standard gamepad layout mapping.
//
// StandardGamepadAxisValue is concurrent safe.
func StandardGamepadAxisValue(id GamepadID, axis StandardGamepadAxis) float64 {
g := gamepad.Get(id)
if g == nil {
return 0
}
return g.StandardAxisValue(axis)
}
// StandardGamepadButtonValue returns a float value [0.0 - 1.0] of the given gamepad (id)'s standard button (button).
//
// StandardGamepadButtonValue returns 0 when the gamepad doesn't have a standard gamepad layout mapping.
//
// StandardGamepadButtonValue is concurrent safe.
func StandardGamepadButtonValue(id GamepadID, button StandardGamepadButton) float64 {
g := gamepad.Get(id)
if g == nil {
return 0
}
return g.StandardButtonValue(button)
}
// IsStandardGamepadButtonPressed reports whether the given gamepad (id)'s standard gamepad button (button) is pressed.
//
// IsStandardGamepadButtonPressed returns false when the gamepad doesn't have a standard gamepad layout mapping.
//
// IsStandardGamepadButtonPressed is concurrent safe.
func IsStandardGamepadButtonPressed(id GamepadID, button StandardGamepadButton) bool {
g := gamepad.Get(id)
if g == nil {
return false
}
return g.IsStandardButtonPressed(button)
}
2021-07-19 19:53:13 +02:00
// IsStandardGamepadLayoutAvailable reports whether the gamepad (id) has a standard gamepad layout mapping.
//
// IsStandardGamepadLayoutAvailable is concurrent-safe.
func IsStandardGamepadLayoutAvailable(id GamepadID) bool {
g := gamepad.Get(id)
if g == nil {
return false
}
return g.IsStandardLayoutAvailable()
}
// IsStandardGamepadAxisAvailable reports whether the standard gamepad axis is available on the gamepad (id).
//
// IsStandardGamepadAxisAvailable is concurrent-safe.
func IsStandardGamepadAxisAvailable(id GamepadID, axis StandardGamepadAxis) bool {
g := gamepad.Get(id)
if g == nil {
return false
}
return g.IsStandardAxisAvailable(axis)
}
// IsStandardGamepadButtonAvailable reports whether the standard gamepad button is available on the gamepad (id).
//
// IsStandardGamepadButtonAvailable is concurrent-safe.
func IsStandardGamepadButtonAvailable(id GamepadID, button StandardGamepadButton) bool {
g := gamepad.Get(id)
if g == nil {
return false
}
return g.IsStandardButtonAvailable(button)
}
2021-08-23 15:08:07 +02:00
// UpdateStandardGamepadLayoutMappings parses the specified string mappings in SDL_GameControllerDB format and
// updates the gamepad layout definitions.
//
2021-08-23 15:08:07 +02:00
// UpdateStandardGamepadLayoutMappings reports whether the mappings were applied,
// and returns an error in case any occurred while parsing the mappings.
//
2021-08-23 15:08:07 +02:00
// One or more input definitions can be provided separated by newlines.
// In particular, it is valid to pass an entire gamecontrollerdb.txt file.
// Note though that Ebitengine already includes its own copy of this file,
// so this call should only be necessary to add mappings for hardware not supported yet;
2021-08-23 15:08:07 +02:00
// ideally games using the StandardGamepad* functions should allow the user to provide mappings and
// then call this function if provided.
// When using this facility to support new hardware, please also send a pull request to
// https://github.com/gabomdq/SDL_GameControllerDB to make your mapping available to everyone else.
//
// A platform field in a line corresponds with a GOOS like the following:
//
2022-08-03 13:48:02 +02:00
// "Windows": GOOS=windows
// "Mac OS X": GOOS=darwin (not ios)
// "Linux": GOOS=linux (not android)
// "Android": GOOS=android
// "iOS": GOOS=ios
// "": Any GOOS
//
// On platforms where gamepad mappings are not managed by Ebitengine, this always returns false and nil.
//
// UpdateStandardGamepadLayoutMappings is concurrent-safe.
//
// UpdateStandardGamepadLayoutMappings mappings take effect immediately even for already connected gamepads.
//
// UpdateStandardGamepadLayoutMappings works atomically. If an error happens, nothing is updated.
func UpdateStandardGamepadLayoutMappings(mappings string) (bool, error) {
if err := gamepaddb.Update([]byte(mappings)); err != nil {
return false, err
}
return true, nil
}
// TouchID represents a touch's identifier.
2022-02-06 10:30:31 +01:00
type TouchID = ui.TouchID
// AppendTouchIDs appends the current touch states to touches, and returns the extended buffer.
// Giving a slice that already has enough capacity works efficiently.
//
// If you want to know whether a touch started being pressed in the current frame,
// use inpututil.JustPressedTouchIDs
//
// AppendTouchIDs doesn't append anything when there are no touches.
// AppendTouchIDs always does nothing on desktops.
//
// AppendTouchIDs is concurrent-safe.
func AppendTouchIDs(touches []TouchID) []TouchID {
return ui.Get().Input().AppendTouchIDs(touches)
}
// TouchIDs returns the current touch states.
//
2022-09-27 20:24:36 +02:00
// Deprecated: as of v2.2. Use AppendTouchIDs instead.
func TouchIDs() []TouchID {
return AppendTouchIDs(nil)
}
// TouchPosition returns the position for the touch of the specified ID.
//
// If the touch of the specified ID is not present, TouchPosition returns (0, 0).
//
// TouchPosition is cuncurrent-safe.
func TouchPosition(id TouchID) (int, int) {
return ui.Get().Input().TouchPosition(id)
}