Joypad handling

OSLib includes functions to read keys in a simpler and more effective way, with functions to get back the buttons which have just been pressed, apply an autorepeat for example.

The principle is simple, you call oslReadKeys() in each frame, it fills a structure named osl_keys which contains all the informations about keys. oslReadKeys returns the pointer to this structure, I advise you to use the returned variable than the global variable (it's cleaner). Here are two examples:

//Example of something to not to do (risk of not working anymore in the future)
while (!osl_quit)
{
	oslReadKeys();
	if (osl_keys->pressed.cross)
		oslDebug("Cross has been pressed");
}
//This is better
OSL_CONTROLLER *k;
while (!osl_quit)
{
	k = oslReadKeys();
	if (k->pressed.cross)
		oslDebug("Cross has been pressed");
}

As said upwards and in the examples, everything is written in a structure of type OSL_CONTROLLER. Here is the definition:

typedef struct		{
	union		{
		struct		{
			int select:1, reserved1:2, start:1;
			int up:1, right:1, down:1, left:1;
			int L:1, R:1, reserved2:2;
			int triangle:1, circle:1, cross:1, square:1;
			int home:1, hold:1, reserved3:5, note:1;
		};
		unsigned int value;
	} held;							//Held keys
	union		{
		struct		{
			int select:1, reserved1:2, start:1;
			int up:1, right:1, down:1, left:1;
			int L:1, R:1, reserved2:2;
			int triangle:1, circle:1, cross:1, square:1;
			int home:1, hold:1, reserved3:5, note:1;
		};
		unsigned int value;
	} pressed;						//Pressed keys
	int autoRepeatInit;					//Autorepeat initialization time
	int autoRepeatInterval;					//Autorepeat trigger interval
	int autoRepeatMask;					//Keys concerned by autorepeat feature
	int autoRepeatCounter;					//Counter (internal)
	signed char analogX;					//Horizontal stick position (-128 to +127)
	signed char analogY;					//Verticale stick position
} OSL_CONTROLLER;

The held members are the held keys. It is simply the current joypad state, without any particular operation. The pressed members indicate on the other hand when a touch has just been pressed. It is useful for menus for example. You can also define an autorepeat in order to if the user press a key for a long time, it will appear several times in the pressed member. Nothing more to do, and you will have a natural and functional menu for the user. AnalogX and analogY are the analog stick horizontal and vertical positions, between -128 and 127. However, before using it in your game, make some tests on real hardware, because this joystick is really not very precise and you would not want it to remain blocked in a direction while the user released it because you have a too high sensibility.

The autoRepeatInit member indicates the necessary number of calls so that a pushed button begins to be considered as autorepeated. For example, if you call this function once by frame and your game runs at 60 FPS, you can see it to 30, so if the user holds for example the 'down' button during 0.5 seconds, it will begin to be repeated at each autoRepeatInterval value. A functional menu could have 40 to autoRepeatInit and 8 to autoRepeatInterval with the game runs at 60 fps. If you use frameskipping, make sure that oslReadKeys is called even if your skip value is true, so that you are sure that even with a 20 fps framerate, the game engine will in fact run at 60 fps and controls will remain functional. Regarding the global structure osl_keys, you can define its parameters by use of macros:

oslSetKeyAutorepeat(keys,init,interval);			//All in one
oslSetKeyAutorepeatMask(mask);				//Mask (keys concerned by the autorepeat feature)
oslSetKeyAutorepeatInit(value);
oslSetKeyAutorepeatInterval(value);

By default, only the following keys are concerned by autorepeat: OSL_KEYMASK_UP, OSL_KEYMASK_RIGHT, OSL_KEYMASK_DOWN, OSL_KEYMASK_LEFT, OSL_KEYMASK_R, OSL_KEYMASK_L. Here is an example to set autorepeat for the left and right keys:

oslSetKeyAutorepeat(OSL_KEYMASK_LEFT|OSL_KEYMASK_RIGHT, 40, 8);