Joypad handling

OSLib inclui funções para ler a teclas de maneira simple e de forma mais efetiva, com funções que capturam os botões que foram pressionados, aplicam um auto-repetimento por exemplo.

O princícpio é simples, você chama oslReadKeys() em cada frame, isto preenche a estrutura nomeada osl_keys que contém todas as informações sobre a tecla. oslReadKeys retorna o ponteiro para a estrutura

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, no qual eu recomendo usar a variável global (é mais limpo). Aqui há dois exemplos:

//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");
}

Como foi dito acima, tudo é escrito na estrutura do tipo OSL_CONTROLLER. Aqui está a definição da mesma:

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;

Os membros da estrutura prendidos são as teclas pressionadas. Isto é simplismente o corrente estado do joypad, sem nenhuma operação particular. Os membros da estrutura pressionados indicam em outras palavras, que um toque na tecla foi feito. Isso é útil para menus, por exemplo. Você pode definir um autorepeat para o caso do usuário pressionar a tecla por um longo período de tempo. Sem mais nada para fazer, você terá um natural e funcional menu para o usuário. AnalogX e AnalogY são as posições vertical e horizontal do joystick com valores entre -128 e 127. Entretanto, antes de usa-lo no seu game, faça alguns testes no hardware real, porque esse joistick não é realmente muito preciso.

O membro autoRepeatInit indica o número necessário de chamadas que um botão pressionado precisa para ser considerado "autorepetido". Por exemplo, se você chamar essa função uma vez por frame e seu jogo rodar a 60 FPS (frame per second), você poderá ve-lo em 30, portanto, se o usuário segurar por exemplo o botão "para baixo" durante 0.5 segundos, ele iniciará a repetição para cada valor de autoRepeatInterval. Um menu funcional tem 40 para autoRepeatInit e 8 para autoRepeatInterval com o jogo rodando a 60 FPS. Se você usar frameskipping (salto de frames), tenha certeza de que oslReadKeys é chamado sempre que o seu valor de salto for verdadeiro (true), com isso você terá certeza 20 fps funcionais. A respeito da estrutura global de osl_keys, você pode definir esse parametro para o uso de macros:

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

Por default, apenas as seguintes teclas sao entendidas para autorepeat: OSL_KEYMASK_UP, OSL_KEYMASK_RIGHT, OSL_KEYMASK_DOWN, OSL_KEYMASK_LEFT, OSL_KEYMASK_R, OSL_KEYMASK_L. Aqui está um exemplo para setar o autorepeat para as teclas esquerda e direita:

oslSetKeyAutorepeat(OSL_KEYMASK_LEFT|OSL_KEYMASK_RIGHT, 40, 8);