sgdk: joy.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Defines | Typedefs | Functions
joy.h File Reference

General controller support. More...

Go to the source code of this file.

## Defines

#define | PORT_1 0x0000
#define | PORT_2 0x0001
#define | JOY_1 0x0000
#define | JOY_2 0x0001
#define | JOY_3 0x0002
#define | JOY_4 0x0003
#define | JOY_5 0x0004
#define | JOY_6 0x0005
#define | JOY_7 0x0006
#define | JOY_8 0x0007
#define | JOY_NUM 0x0008
#define | JOY_ALL 0xFFFF
#define | BUTTON_UP 0x0001
#define | BUTTON_DOWN 0x0002
#define | BUTTON_LEFT 0x0004
#define | BUTTON_RIGHT 0x0008
#define | BUTTON_A 0x0040
#define | BUTTON_B 0x0010
#define | BUTTON_C 0x0020
#define | BUTTON_START 0x0080
#define | BUTTON_X 0x0400
#define | BUTTON_Y 0x0200
#define | BUTTON_Z 0x0100
#define | BUTTON_MODE 0x0800
#define | BUTTON_LMB 0x0040
#define | BUTTON_MMB 0x0010
#define | BUTTON_RMB 0x0020
#define | BUTTON_DIR 0x000F
#define | BUTTON_BTN 0x0FF0
#define | BUTTON_ALL 0x0FFF
#define | JOY_TYPE_PAD3 0x00
#define | JOY_TYPE_PAD6 0x01
#define | JOY_TYPE_MOUSE 0x02
#define | JOY_TYPE_TRACKBALL 0x03
#define | JOY_TYPE_MENACER 0x04
#define | JOY_TYPE_JUSTIFIER 0x05
#define | JOY_TYPE_PHASER 0x06
#define | JOY_TYPE_UNKNOWN 0x0F
#define | PORT_TYPE_MENACER 0x00
#define | PORT_TYPE_JUSTIFIER 0x01
#define | PORT_TYPE_MOUSE 0x03
#define | PORT_TYPE_TEAMPLAYER 0x07
#define | PORT_TYPE_PAD 0x0D
#define | PORT_TYPE_UNKNOWN 0x0F
#define | PORT_TYPE_EA4WAYPLAY 0x10
#define | PORT_TYPE_UKNOWN PORT_TYPE_UNKNOWN
#define | JOY_SUPPORT_OFF 0x00
#define | JOY_SUPPORT_3BTN 0x01
#define | JOY_SUPPORT_6BTN 0x02
#define | JOY_SUPPORT_MOUSE 0x03
#define | JOY_SUPPORT_TRACKBALL 0x04
#define | JOY_SUPPORT_TEAMPLAYER 0x05
#define | JOY_SUPPORT_EA4WAYPLAY 0x06
#define | JOY_SUPPORT_MENACER 0x07
#define | JOY_SUPPORT_JUSTIFIER_BLUE 0x08
#define | JOY_SUPPORT_JUSTIFIER_BOTH 0x09
#define | JOY_SUPPORT_PHASER 0x0A
#define | JOY_SUPPORT_ANALOGJOY 0x0B
#define | JOY_SUPPORT_KEYBOARD 0x0C

## Typedefs

typedef void | JoyEventCallback (u16 joy, u16 changed, u16 state)
| Joypad event callback.

## Functions

void | JOY_init ()
| Initialize the controller sub system.
void | JOY_reset ()
| Reset the controller sub system.
void | JOY_setEventHandler (JoyEventCallback *CB)
| Set the callback function for controller state changed. SGDK provides facilities to detect state change on controller. It update controllers state at each V Blank period and fire event if a state change is detected.
void | JOY_setSupport (u16 port, u16 support)
| Set peripheral support for the specified port. By default ports are configured to only enable support for joypads, unless a pad is not detected. In that case, a multitap or mouse is enabled if present.
u8 | JOY_getPortType (u16 port)

Get peripheral type for the specified port.
The peripheral type for each port is automatically detected during JOY_init() / JOY_reset() call.
This function returns that type to help decide how the port support should be set.
Types greater than 15 are not derived via Sega's controller ID method.

u8 | JOY_getJoypadType (u16 joy)

Get joypad peripheral type connected to the specified joypad port.
The joypad peripheral type for each port is automatically detected during JOY_init() or JOY_reset() call.
Prefer this method over JOY_getPortType(..) when you need to get information
about peripheral connected to multi joypad adapter (as the Sega TeamPlayer).

u16 | JOY_readJoypad (u16 joy)
| Get joypad state.
s16 | JOY_readJoypadX (u16 joy)
| Get joypad X axis.
s16 | JOY_writeJoypadX (u16 joy, u16 pos)
| Write joypad X axis.
s16 | JOY_readJoypadY (u16 joy)
| Get joypad Y axis.
s16 | JOY_writeJoypadY (u16 joy, u16 pos)
| Write joypad Y axis.
void | JOY_waitPressBtn ()
| Wait until a button is pressed on any connected controller.
u16 | JOY_waitPressBtnTime (u16 ms)
| Wait the specified amount of time or until a button is pressed on any connected controller.
u16 | JOY_waitPress (u16 joy, u16 btn)
| Wait for specified button to be pressed on specified joypad.
u16 | JOY_waitPressTime (u16 joy, u16 btn, u16 ms)
| Wait for specified button(s) to be pressed on specified joypad.
void | JOY_update ()
| Manual update joypad state. By default the library update joypad state on V interrupt process. Calling this method will force to update joypad state now.

## Detailed Description

General controller support.

Author:
  Chilly Willy
  Stephane Dallongeville

Date:
  05/2012

This unit provides methods to read controller state.
Here is the list of supported controller device:

- 3 buttons joypad
- 6 buttons joypad
- Sega Mouse
- Sega Team Player adapter
- EA 4-Way Play
- the Menacer
- the Justifier
- Sega Master System pad
- Sega Trackball
- Sega Phaser

Although Sega Master System pad, trackball, and Phaser are supported, they aren't automatically detected on JOY_init().
Another caveat is that although the Menacer and Justifier are automatically recognized and supported, the support is not enabled until the programmer tells it to because of the extra overhead that lightguns add. This way, SGDK defaults to a lower overhead state for controllers. Games that can use lightguns can check and enable the lightgun as part of the init process, while normal games can ignore that and simply count on the default init state for controllers.
Note that mice are enabled by default by JOY_init() and will return emulated pad values for reading the port as if it were a controller.
This allows using a mouse as a pad for SGDK games. However, mice use a little more overhead than pads, so a game that doesn't use mice as mice and wants every last scrap of speed should check if mice are connected and turn them off to get just that extra little bit of speed.
If you have an existing SGDK based game that needs every last bit of speed and doesn't check for mice, unplug any mice for extra speed. Mice are only enabled if detected.

## Define Documentation

#define PORT_TYPE_UKNOWN PORT_TYPE_UNKNOWN

Deprecated:
  Use PORT_TYPE_UNKNOWN instead

## Typedef Documentation

typedef void JoyEventCallback(u16 joy, u16 changed, u16 state)

Joypad event callback.

Parameters:

  joy

  Joypad which generated the event.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)
  JOY_ALL = joypad 1 | joypad 2 | ... | joypad 8

  change

  Changed state (button for which state changed).
  BUTTON_UP = UP button
  BUTTON_DOWN = DOWN button
  BUTTON_LEFT = LEFT button
  BUTTON_RIGHT = RIGHT button
  BUTTON_A = A button
  BUTTON_B = B button
  BUTTON_C = C button
  BUTTON_START = START button
  BUTTON_X = X button
  BUTTON_Y = Y button
  BUTTON_Z = Z button
  BUTTON_MODE = MODE button
  BUTTON_LMB = Alias for A button for mouse
  BUTTON_MMB = Alias for B button for mouse
  BUTTON_RMC = Alias for C button for mouse

  state | Current joypad state. Ex: Test if button START on joypad 1 just get pressed: joy = JOY_1; changed = BUTTON_START; state = BUTTON_START | (previous state)

## Function Documentation

u8 JOY_getJoypadType | ( | u16 | joy | ) |

Get joypad peripheral type connected to the specified joypad port.
The joypad peripheral type for each port is automatically detected during JOY_init() or JOY_reset() call.
Prefer this method over JOY_getPortType(..) when you need to get information
about peripheral connected to multi joypad adapter (as the Sega TeamPlayer).

Parameters:

  joy

  Joypad port we query type.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 TeamPlayer connected)

Returns:
  joypad peripheral type.
  JOY_TYPE_PAD3 = 3 buttons joypad
  JOY_TYPE_PAD6 = 6 buttons joypad
  JOY_TYPE_MOUSE = Sega Mouse
  JOY_TYPE_TRACKBALL = Sega trackball
  JOY_TYPE_MENACER = Sega Menacer gun
  JOY_TYPE_JUSTIFIER = Sega Justifier gun
  JOY_TYPE_UNKNOWN = Unknow adaptater or not connected

u8 JOY_getPortType | ( | u16 | port | ) |

Get peripheral type for the specified port.
The peripheral type for each port is automatically detected during JOY_init() / JOY_reset() call.
This function returns that type to help decide how the port support should be set.
Types greater than 15 are not derived via Sega's controller ID method.

Parameters:

  port | Port we want to get the peripheral type. PORT_1 = port 1 PORT_2 = port 2

Returns:
  type Peripheral type.
  PORT_TYPE_MENACER = Sega Menacer
  PORT_TYPE_JUSTIFIER = Konami Justifier
  PORT_TYPE_MOUSE = Sega MegaMouse
  PORT_TYPE_TEAMPLAYER = Sega TeamPlayer
  PORT_TYPE_PAD = Sega joypad
  PORT_TYPE_UNKNOWN = unidentified or no peripheral
  PORT_TYPE_EA4WAYPLAY = EA 4-Way Play
  Ex: get peripheral type in port 1
  type = JOY_getPortType(PORT_1);

void JOY_init | ( |  | ) |

Initialize the controller sub system.

Software and hardware controller port initialization (reset and devices detection).
Automatically called at SGDK initialization, no need to call it manually.

u16 JOY_readJoypad | ( | u16 | joy | ) |

Get joypad state.

Parameters:

  joy

  Joypad we query state.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)
  JOY_ALL = joypad 1 | joypad 2 | ... | joypad 8

Returns:
  joypad state.
  BUTTON_UP = UP button
  BUTTON_DOWN = DOWN button
  BUTTON_LEFT = LEFT button
  BUTTON_RIGHT = RIGHT button
  BUTTON_A = A button
  BUTTON_B = B button
  BUTTON_C = C button
  BUTTON_START = START button
  BUTTON_X = X button
  BUTTON_Y = Y button
  BUTTON_Z = Z button
  BUTTON_MODE = MODE button
  BUTTON_LMB = Alias for A button for mouse
  BUTTON_MMB = Alias for B button for mouse
  BUTTON_RMC = Alias for C button for mouse
  Ex : Test if button START or A is pressed on joypad 1 :
  if (JOY_readJoypad(JOY_1) & (BUTTON_START | BUTTON_A))

s16 JOY_readJoypadX | ( | u16 | joy | ) |

Get joypad X axis.

Parameters:

  joy

  Joypad we query state.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)

Returns:
  joypad X axis.
  A mouse returns signed axis data. The change in this value indicates movement -
  to the right for positive changes, or left for negative changes.
  A light gun returns the unsigned screen X coordinate. This is not calibrated;
  Calibration is left to the game to handle. The value is -1 if the gun is not
  pointed at the screen, or the screen is too dim to detect.
  Ex : Get X axis of pad 2 :
  countX = JOY_readJoypadX(JOY_2);

s16 JOY_readJoypadY | ( | u16 | joy | ) |

Get joypad Y axis.

Parameters:

  joy

  Joypad we query state.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)

Returns:
  joypad Y axis.
  A mouse returns signed axis data. The change in this value indicates movement -
  upwards for positive changes, or downwards for negative changes.
  A light gun returns the unsigned screen Y coordinate. This is not calibrated;
  Calibration is left to the game to handle. The value is -1 if the gun is not
  pointed at the screen, or the screen is too dim to detect.
  Ex : Get Y axis of pad 2 :
  countY = JOY_readJoypadY(JOY_2);

void JOY_reset | ( |  | ) |

Reset the controller sub system.

It will reset the controller port state and perform device detectionSoftware and hardware controller port initialization.
Automatically called at SGDK initialization, no need to call it manually.

void JOY_setEventHandler | ( | JoyEventCallback * | CB | ) |

Set the callback function for controller state changed.
SGDK provides facilities to detect state change on controller.
It update controllers state at each V Blank period and fire event if a state change is detected.

Parameters:

  CB

  Callback to call when controller(s) state changed.
  The function prototype should reply to _joyEventCallback type :
  void function(u16 joy, u16 changed, u16 state);
  Ex 1 : if player 1 just pressed START button you receive :
  joy = JOY_1, changed = BUTTON_START, state = BUTTON_START
  Ex 2 : if player 2 just released the A button you receive :
  joy = JOY_2, changed = BUTTON_A, state = 0

void JOY_setSupport | ( | u16 | port,
|  | u16 | support
| ) |  |

Set peripheral support for the specified port.
By default ports are configured to only enable support for joypads, unless
a pad is not detected. In that case, a multitap or mouse is enabled if
present.

Parameters:

  port | Port we want to set support. PORT_1 = port 1 PORT_2 = port 2

  support

  Peripheral support.
  JOY_SUPPORT_OFF = No peripheral support
  JOY_SUPPORT_3BTN = 3 button joypad
  JOY_SUPPORT_6BTN = 6 button joypad
  JOY_SUPPORT_TRACKBALL = Sega Sports Pad (SMS trackball)
  JOY_SUPPORT_MOUSE = Sega MegaMouse
  JOY_SUPPORT_TEAMPLAYER = Sega TeamPlayer
  JOY_SUPPORT_EA4WAYPLAY = EA 4-Way Play
  JOY_SUPPORT_MENACER = Sega Menacer
  JOY_SUPPORT_JUSTIFIER_BLUE = Konami Justifier (blue gun only)
  JOY_SUPPORT_JUSTIFIER_BOTH = Konami Justifier (both guns)
  JOY_SUPPORT_ANALOGJOY = Sega analog joypad (not yet supported)
  JOY_SUPPORT_KEYBOARD = Sega keyboard (not yet supported)
  Ex: enable support for MegaMouse on second port
  JOY_setSupport(PORT_2, JOY_SUPPORT_MOUSE);

u16 JOY_waitPress | ( | u16 | joy,
|  | u16 | btn
| ) |  |

Wait for specified button to be pressed on specified joypad.

Parameters:

  joy | Joypad we want to check state (see JOY_readJoypad()). You can also use JOY_ALL to check on any connected controller.

  btn

  button(s) we want to check state.
  BUTTON_UP = UP button
  BUTTON_DOWN = DOWN button
  BUTTON_LEFT = LEFT button
  BUTTON_RIGHT = RIGHT button
  BUTTON_A = A button
  BUTTON_B = B button
  BUTTON_C = C button
  BUTTON_START = START button
  BUTTON_X = X button
  BUTTON_Y = Y button
  BUTTON_Z = Z button
  BUTTON_MODE = MODE button
  BUTTON_DIR = Any of the direction buttons (UP, DOWN, LEFT or RIGHT)
  BUTTON_BTN = Any of the non direction buttons (A, B, C, START, X, Y, Z, MODE)
  BUTTON_ALL = Any of all buttons
  BUTTON_LMB = Alias for A button for mouse
  BUTTON_MMB = Alias for B button for mouse
  BUTTON_RMC = Alias for C button for mouse

Returns:
  The button actually pressed or FALSE if none of specified button has be pressed in the given time.
  Ex: if we want to wait any of direction buttons or button A is pressed on joypad 1 :
  pressed = JOY_waitJoypad(JOY_1, BUTTON_DIR | BUTTON_A);

u16 JOY_waitPressTime | ( | u16 | joy,
|  | u16 | btn,
|  | u16 | ms
| ) |  |

Wait for specified button(s) to be pressed on specified joypad.

Parameters:

  joy | Joypad we want to check state (see JOY_readJoypad()). You can also use JOY_ALL to check on any connected controller.

  btn

  button(s) we want to check state.
  BUTTON_UP = UP button
  BUTTON_DOWN = DOWN button
  BUTTON_LEFT = LEFT button
  BUTTON_RIGHT = RIGHT button
  BUTTON_A = A button
  BUTTON_B = B button
  BUTTON_C = C button
  BUTTON_START = START button
  BUTTON_X = X button
  BUTTON_Y = Y button
  BUTTON_Z = Z button
  BUTTON_MODE = MODE button
  BUTTON_DIR = Any of the direction buttons (UP, DOWN, LEFT or RIGHT)
  BUTTON_BTN = Any of the non direction buttons (A, B, C, START, X, Y, Z, MODE)
  BUTTON_ALL = Any of all buttons
  BUTTON_LMB = Alias for A button for mouse
  BUTTON_MMB = Alias for B button for mouse
  BUTTON_RMC = Alias for C button for mouse

  ms | maximum time in ms to wait for the button press action (0 means wait infinitely).

Returns:
  The button actually pressed or FALSE if none of specified button has be pressed in the given time.
  Ex: if we want to wait a maximum of 5 secondes for any of direction buttons
  or button A to be pressed on joypad 1:
  pressed = JOY_waitJoypad(JOY_1, BUTTON_DIR | BUTTON_A, 5000);

s16 JOY_writeJoypadX | ( | u16 | joy,
|  | u16 | pos
| ) |  |

Write joypad X axis.

Parameters:

  joy

  Joypad we query state.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)

  pos | Desired X position for joypad.

s16 JOY_writeJoypadY | ( | u16 | joy,
|  | u16 | pos
| ) |  |

Write joypad Y axis.

Parameters:

  joy

  Joypad we query state.
  JOY_1 = joypad 1
  JOY_2 = joypad 2
  ... = ...
  JOY_8 = joypad 8 (only possible with 2 teamplayers connected)

  pos | Desired Y position for joypad.

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines