int install_joystick(int type);
Inicializa el joystick y calibra el valor de la posici�n central. Debe
llamar esto antes que cualquier otra funci�n de joystick, y deber�a
asegurarse que el joystick est� centrado en ese momento. Devuelve cero si
no hubo problemas. El par�metro type debe ser uno de estos valores:
JOY_TYPE_AUTODETECT
Intenta autodetectar el joystick instalado. En realidad no es posible
distinguir entre todos las posibles configuraciones, por lo que esta
rutina s�lo puede elegir el controlador de joystick est�ndar,
Sidewinder o Gamepad Pro, pero usar� informaci�n del fichero de
configuraci�n si �ste existe (el fichero puede ser creado usando la
utilidad setup o llamando la funci�n save_joystick_data()), por lo que
siempre puede usar JOY_TYPE_AUTODETECT en su c�digo y elegir el tipo
de hardware exacto desde el programa setup.
JOY_TYPE_NONE
Controlador vac�o para m�quinas sin joystick.
JOY_TYPE_STANDARD
Un joystick normal de dos botones.
JOY_TYPE_2PADS
Modo de joystick dual (dos joysticks, cada uno con dos botones).
JOY_TYPE_4BUTTON
Activa los botones extra de un joystick de 4 botones.
JOY_TYPE_6BUTTON
Activa los botones extra de un joystick de 6 botones.
JOY_TYPE_8BUTTON
Activa los botones extra de un joystick de 8 botones.
JOY_TYPE_FSPRO
Joystick CH Flightstick Pro o compatible, que tiene cuatro botones,
un mando de gases anal�gico, y un sombrero de 4 direcciones.
JOY_TYPE_WINGEX
Un Logitech Wingman Extreme, que deber�a funcionar con cualquier
joystick compatible Thrustmaster Mk.I. Tiene soporte para cuatro
botones y un sombrero. Esto tambi�n funciona con el Wingman Warrior,
si conectas el conector de 15 pins (�desconecta el conector de 9
pins!) y si ajustas el peque�o interruptor de adelante a la posici�n
"H" (sin embargo, no podr�s usar el mando de gases o el 'spinner').
JOY_TYPE_SIDEWINDER
El pad digital Microsoft Sidewinder (soporta hasta cuatro aparatos,
cada uno con diez botones y un control digital de direcci�n).
JOY_TYPE_GAMEPAD_PRO
El Gravis GamePad Pro (soporta dos mandos, cada uno con diez botones y
un control digital de direcci�n).
JOY_TYPE_SNESPAD_LPT1
JOY_TYPE_SNESPAD_LPT2
JOY_TYPE_SNESPAD_LPT3
Pads SNES conectados a los puertos LPT1, LPT2, y LPT3 respectivamente.
JOY_TYPE_WINGWARRIOR
El joystick Wingman Warrior.
Tan pronto como haya instalado el m�dulo de joystick, podr� leer el estado de los botones y la informaci�n de direcci�n digital (on/off), que puede ser suficiente para ciertos juegos. Sin embargo si quiere entrada anal�gica total, necesita usar las funciones calibrate_joystick() para medir el rango exacto de entrada: lea m�s abajo.
void remove_joystick();
Quita el controlador de joystick. Normalmente no hace falta llamar esto,
porque allegro_exit() lo har� por usted.
int poll_joystick();
A diferencia del rat�n o el teclado, el joystick no es controlado por
interrupciones, por lo que debe llamar esta funci�n una y otra vez para
actualizar los valores globales de posici�n.
extern int num_joysticks;
Variables globales que indican el n�mero de joysticks activos. Los
controlador actuales soportan un m�ximo de cuatro dispositivos.
extern JOYSTICK_INFO joy[n];
Array global de informaci�n de estado del joystick, que es actualizado
por la funci�n poll_joystick(). S�lo el primer elemento num_joysticks
tendr� informaci�n �til. La estructura JOYSTICK_INFO est� definida as�:
typedef struct JOYSTICK_INFO
{
int flags; - biestable de estado de este joystick
int num_sticks; - �cu�ntos joysticks activos?
int num_buttons; - �cu�ntos botones?
JOYSTICK_STICK_INFO stick[n]; - informaci�n de estado del stick
JOYSTICK_BUTTON_INFO button[n]; - informaci�n de estado de los
botones
} JOYSTICK_INFO;
El estado de los botones es almacenado en la estructura:
typedef struct JOYSTICK_BUTTON_INFO
{
int b; - biestable booleano on/off
char *name; - descripci�n de este bot�n
} JOYSTICK_BUTTON_INFO;
Puede ense�ar los nombres de los botones como parte de una pantalla de
configuraci�n en la que el usuario elige qu� funci�n desempe�ar� cada
bot�n en su juego, pero en situaciones simples puede asumir con
seguridad que los dos primeros elementos del array button ser�n siempre
los controles principales de disparo.
Cada joystick proveer� una o m�s entradas stick, de varios tipos. Estas pueden ser controles digitales que tienen siempre un valor espec�fico (ej. un gamepad, el sombrero del Flightstick Pro o Wingman Extreme, o un joystick normal que todav�a no ha sido calibrado), o pueden ser entradas anal�gicas con un rango suave de movimiento. Las palancas pueden tener un n�mero diferente de ejes, por ejemplo un controlador direccional normal tiene dos, pero el mando de gases del Flightstick Pro s�lo tiene un eje, y es posible que el sistema pueda ser expandido en el futuro para soportar controladores 3d. La entrada de la palanca est� descrita por la estructura:
typedef struct JOYSTICK_STICK_INFO
{
int flags; - biestable de estado
int num_axis; - �cu�ntos ejes tenemos?
JOYSTICK_AXIS_INFO axis[n]; - informaci�n de estado del eje
char *name; - descripci�n de este stick
} JOYSTICK_STICK_INFO;
Un s�lo joystick puede proveer diferentes entradas de joystick, pero
puede asumir con seguridad que el primer elemento del array stick ser�
el controlador principal de direcci�n.
La informaci�n sobre los ejes del mando est� almacenada en la subestructura:
typedef struct JOYSTICK_AXIS_INFO
{
int pos; - posici�n anal�gica del eje
int d1, d2; - posici�n digital del eje
char *name; - descripci�n de este eje
} JOYSTICK_AXIS_INFO;
Esto se da tanto entrada digital en el campo pos (que va de -128 a 128 o
de 0 a 255, dependiendo del tipo de control) como valores digitales en
los campos d1 y d2. Por ejemplo, cuando describe la posici�n del eje X,
el campo pos contendr� la posici�n horizontal de joystick, d1 ser�
activado si mueves a la izquierda, y d2 ser� activado si mueves a la
derecha. Allegro rellenar� todos estos valores sin importar el tipo de
joystick que est� conectado, emulando el campo pos para joysticks
digitales poni�ndolo a las posiciones m�nima, central y m�xima, y
emulando los valores d1 y d2 con joysticks anal�gicos comparando la
posici�n actual con el punto central.
El campo de biestables puede tener cualquier combinaci�n de los siguientes biestables de bit:
JOYFLAG_DIGITAL
Este control tiene entrada digital.
JOYFLAG_ANALOGUE
Este control tiene entrada anal�gica.
JOYFLAG_CALIB_DIGITAL
Este control ser� capaz de proveer entrada digital una vez sea
calibrado, pero ahora no lo hace.
JOYFLAG_CALIB_ANALOGUE
Este control ser� capaz de proveer entrada anal�gica una vez sea
calibrado, pero ahora no lo hace.
JOYFLAG_CALIBRATE
Indica que este control debe ser calibrado. Muchos dispositivos
requieren m�ltiples pasos de calibraci�n, por lo que puede llamar la
funci�n calibrate_joystick() desde un bucle hasta que esta biestable
desaparezca.
JOYFLAG_SIGNED
Indica que la posici�n anal�gica est� en formato con signo, que va de
-128 a 128. Este es el caso de todos los controles direccionales 2d.
JOYFLAG_UNSIGNED
Indica que la posici�n anal�gica est� en formato sin signo, que va de
0 a 255. Este es el caso de todos los mandos de gases 1d.
Nota para la gente que escribe diferente: en caso que no quiera escribir "analogue", hay varios #defines en allegro.h que le permitir�n escribir "analog" sin problemas.
char *calibrate_joystick_name(int n);
Devuelve una descripci�n textual del siguiente tipo de calibraci�n que
ser� hecha en el joystick especificado, o NULL si no hace falta m�s
calibraci�n.
int calibrate_joystick(int n);
La mayor�a de los joysticks deben ser calibrados antes de poder ser
usados de forma anal�gica. Esta funci�n realiza la siguiente operaci�n en
la serie de calibraci�n para el stick especificado, asumiendo que el
joystick ha sido posicionado de la forma descrita por la llamada previa a
calibrate_joystick_name(), devolviendo cero con �xito. Por ejemplo, una
rutina simple para calibrar los joysticks puede ser as�:
int i;int save_joystick_data(char *filename);for (i=0; i<;num_joysticks; i++) { while (joy[i].flags & JOYFLAG_CALIBRATE) { char *msg = calibrate_joystick_name(i); printf("%s, y pulsa una tecla\n", msg); readkey(); if (calibrate_joystick(i) != 0) { printf("�oops!\n"); exit(1); } } }
int load_joystick_data(char *filename);
Recupera los datos de calibrado previamente almacenados por
save_joystick_data() o la utilidad setup. Esto ajusta todos los aspectos
del c�digo de joystick: ni si quiera debe llamar initialise_joystick()
si est� usando esta funci�n. Pasa NULL como filename para leer los datos
del fichero de configuraci�n seleccionado actualmente. Devuelve cero si
no hubo problemas: si falla, el estado del joystick queda indefinido y
debe reinicializarlo desde el comienzo.