[sdl_omap.git] / docs / html / guideinput.html

<HTML
><HEAD
><TITLE
>Input handling</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="SDL Guide"
HREF="guide.html"><LINK
REL="PREVIOUS"
TITLE="Using OpenGL With SDL"
HREF="guidevideoopengl.html"><LINK
REL="NEXT"
TITLE="Handling the Keyboard"
HREF="guideinputkeyboard.html"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="guidevideoopengl.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="guideinputkeyboard.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="GUIDEINPUT"
></A
>Chapter 3. Input handling</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="guideinput.html#GUIDEINPUTJOYSTICK"
>Handling Joysticks</A
></DT
><DT
><A
HREF="guideinputkeyboard.html"
>Handling the Keyboard</A
></DT
></DL
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="GUIDEINPUTJOYSTICK"
></A
>Handling Joysticks</H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN135"
></A
>Initialization</H2
><P
>The first step in using a joystick in a SDL program is to initialize the Joystick subsystems of SDL. This done by passing the <TT
CLASS="LITERAL"
>SDL_INIT_JOYSTICK</TT
> flag to <A
HREF="sdlinit.html"
><TT
CLASS="FUNCTION"
>SDL_Init</TT
></A
>.  The joystick flag will usually be used in conjunction with other flags (like the video flag) because the joystick is usually used to control something.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN141"
></A
><P
><B
>Example 3-1. Initializing SDL with Joystick Support</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    if (SDL_Init( SDL_INIT_VIDEO | SDL_INIT_JOYSTICK ) &#60; 0)
    {
        fprintf(stderr, "Couldn't initialize SDL: %s\n", SDL_GetError());
        exit(1);
    }</PRE
></DIV
><P
>This will attempt to start SDL with both the video and the joystick subsystems activated.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN145"
></A
>Querying</H2
><P
>If we have reached this point then we can safely assume that the SDL library has been initialized and that the Joystick subsystem is active. We can now call some video and/or sound functions to get things going before we need the joystick. Eventually we have to make sure that there is actually a joystick to work with. It's wise to always check even if you know a joystick will be present on the system because it can also help detect when the joystick is unplugged. The function used to check for joysticks is <A
HREF="sdlnumjoysticks.html"
><TT
CLASS="FUNCTION"
>SDL_NumJoysticks</TT
></A
>.</P
><P
>This function simply returns the number of joysticks available on the system. If it is at least one then we are in good shape. The next step is to determine which joystick the user wants to use. If the number of joysticks available is only one then it is safe to assume that one joystick is the one the user wants to use. SDL has a function to get the name of the joysticks as assigned by the operations system and that function is <A
HREF="sdljoystickname.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickName</TT
></A
>.  The joystick is specified by an index where 0 is the first joystick and the last joystick is the number returned by <TT
CLASS="FUNCTION"
>SDL_NumJoysticks</TT
> - 1.  In the demonstration a list of all available joysticks is printed to stdout.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN154"
></A
><P
><B
>Example 3-2. Querying the Number of Available Joysticks</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    printf("%i joysticks were found.\n\n", SDL_NumJoysticks() );
    printf("The names of the joysticks are:\n");
		
    for( i=0; i &#60; SDL_NumJoysticks(); i++ ) 
    {
        printf("    %s\n", SDL_JoystickName(i));
    }</PRE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN157"
></A
>Opening a Joystick and Receiving Joystick Events</H2
><P
>SDL's event driven architecture makes working with joysticks a snap.  Joysticks can trigger 4 different types of events:
<P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
><A
HREF="sdljoyaxisevent.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_JoyAxisEvent</SPAN
></A
></TD
><TD
>Occurs when an axis changes</TD
></TR
><TR
><TD
><A
HREF="sdljoyballevent.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_JoyBallEvent</SPAN
></A
></TD
><TD
>Occurs when a joystick trackball's position changes</TD
></TR
><TR
><TD
><A
HREF="sdljoyhatevent.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_JoyHatEvent</SPAN
></A
></TD
><TD
>Occurs when a hat's position changes</TD
></TR
><TR
><TD
><A
HREF="sdljoybuttonevent.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_JoyButtonEvent</SPAN
></A
></TD
><TD
>Occurs when a button is pressed or released</TD
></TR
></TBODY
></TABLE
><P
></P
></P
><P
>Events are received from all joysticks opened. The first thing that needs to be done in order to receive joystick events is to call <A
HREF="sdljoystickeventstate.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickEventState</TT
></A
> with the <TT
CLASS="LITERAL"
>SDL_ENABLE</TT
> flag. Next you must open the joysticks that you want to receive envents from. This is done with the <A
HREF="sdljoystickopen.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickOpen</TT
></A
> function. For the example we are only interested in events from the first joystick on the system, regardless of what it may be. To receive events from it we would do this:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN183"
></A
><P
><B
>Example 3-3. Opening a Joystick</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    SDL_Joystick *joystick;

    SDL_JoystickEventState(SDL_ENABLE);
    joystick = SDL_JoystickOpen(0);</PRE
></DIV
><P
>If we wanted to receive events for other joysticks we would open them with calls to <TT
CLASS="FUNCTION"
>SDL_JoystickOpen</TT
> just like we opened joystick 0, except we would store the <SPAN
CLASS="STRUCTNAME"
>SDL_Joystick</SPAN
> structure they return in a different pointer.  We only need the joystick pointer when we are querying the joysticks or when we are closing the joystick.</P
><P
>Up to this point all the code we have is used just to initialize the joysticks in order to read values at run time. All we need now is an event loop, which is something that all SDL programs should have anyway to receive the systems quit events. We must now add code to check the event loop for at least some of the above mentioned events. Let's assume our event loop looks like this:
<PRE
CLASS="PROGRAMLISTING"
>    SDL_Event event;
    /* Other initializtion code goes here */   

    /* Start main game loop here */

    while(SDL_PollEvent(&#38;event))
    {  
        switch(event.type)
        {  
            case SDL_KEYDOWN:
            /* handle keyboard stuff here */				
            break;

            case SDL_QUIT:
            /* Set whatever flags are necessary to */
            /* end the main game loop here */
            break;
        }
    }

    /* End loop here */</PRE
>
To handle Joystick events we merely add cases for them, first we'll add axis handling code. Axis checks can get kinda of tricky because alot of the joystick events received are junk. Joystick axis have a tendency to vary just a little between polling due to the way they are designed. To compensate for this you have to set a threshold for changes and ignore the events that have'nt exceeded the threshold. 10% is usually a good threshold value.  This sounds a lot more complicated than it is. Here is the Axis event handler:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN191"
></A
><P
><B
>Example 3-4. Joystick Axis Events</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    case SDL_JOYAXISMOTION:  /* Handle Joystick Motion */
    if ( ( event.jaxis.value &#60; -3200 ) || (event.jaxis.value &#62; 3200 ) ) 
    {
      /* code goes here */
    }
    break;</PRE
></DIV
><P
>Another trick with axis events is that up-down and left-right movement are two different sets of axes. The most important axis is axis 0 (left-right) and axis 1 (up-down).  To handle them seperatly in the code we do the following:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN195"
></A
><P
><B
>Example 3-5. More Joystick Axis Events</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    case SDL_JOYAXISMOTION:  /* Handle Joystick Motion */
    if ( ( event.jaxis.value &#60; -3200 ) || (event.jaxis.value &#62; 3200 ) ) 
    {
        if( event.jaxis.axis == 0) 
        {
            /* Left-right movement code goes here */
        }

        if( event.jaxis.axis == 1) 
        {
            /* Up-Down movement code goes here */
        }
    }
    break;</PRE
></DIV
><P
>Ideally the code here should use <TT
CLASS="STRUCTFIELD"
><I
>event.jaxis.value</I
></TT
> to scale something. For example lets assume you are using the joystick to control the movement of a spaceship. If the user is using an analog joystick and they push the stick a little bit they expect to move less than if they pushed it a lot. Designing your code for this situation is preferred because it makes the experience for users of analog controls better and remains the same for users of digital controls.</P
><P
>If your joystick has any additional axis then they may be used for other sticks or throttle controls and those axis return values too just with different <TT
CLASS="STRUCTFIELD"
><I
>event.jaxis.axis</I
></TT
> values.</P
><P
>Button handling is simple compared to the axis checking.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN203"
></A
><P
><B
>Example 3-6. Joystick Button Events</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    case SDL_JOYBUTTONDOWN:  /* Handle Joystick Button Presses */
    if ( event.jbutton.button == 0 ) 
    {
        /* code goes here */
    }
    break;</PRE
></DIV
><P
>Button checks are simpler than axis checks because a button can only be pressed or not pressed.  The <TT
CLASS="LITERAL"
>SDL_JOYBUTTONDOWN</TT
> event is triggered when a button is pressed and the <TT
CLASS="LITERAL"
>SDL_JOYBUTTONUP</TT
> event is fired when a button is released. We do have to know what button was pressed though, that is done by reading the <TT
CLASS="STRUCTFIELD"
><I
>event.jbutton.button</I
></TT
> field.</P
><P
>Lastly when we are through using our joysticks we should close them with a call to <A
HREF="sdljoystickclose.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickClose</TT
></A
>. To close our opened joystick 0 we would do this at the end of our program:
<PRE
CLASS="PROGRAMLISTING"
>    SDL_JoystickClose(joystick);</PRE
></P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN214"
></A
>Advanced Joystick Functions</H2
><P
>That takes care of the controls that you can count on being on every joystick under the sun, but there are a few extra things that SDL can support.  Joyballs are next on our list, they are alot like axis with a few minor differences.  Joyballs store relative changes unlike the the absolute postion stored in a axis event. Also one trackball event contains both the change in x and they change in y.  Our case for it is as follows:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN217"
></A
><P
><B
>Example 3-7. Joystick Ball Events</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    case SDL_JOYBALLMOTION:  /* Handle Joyball Motion */
    if( event.jball.ball == 0 )
    {
      /* ball handling */
    }
    break;</PRE
></DIV
><P
>The above checks the first joyball on the joystick. The change in position will be stored in <TT
CLASS="STRUCTFIELD"
><I
>event.jball.xrel</I
></TT
> and <TT
CLASS="STRUCTFIELD"
><I
>event.jball.yrel</I
></TT
>.</P
><P
>Finally we have the hat event. Hats report only the direction they are pushed in. We check hat's position with the bitmasks:

<P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_CENTERED</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_UP</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_RIGHT</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_DOWN</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_LEFT</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
>

Also there are some predefined combinations of the above:
<P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_RIGHTUP</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_RIGHTDOWN</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_LEFTUP</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>SDL_HAT_LEFTDOWN</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
>

Our case for the hat may resemble the following:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN244"
></A
><P
><B
>Example 3-8. Joystick Hat Events</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    case SDL_JOYHATMOTION:  /* Handle Hat Motion */
    if ( event.jhat.value &#38; SDL_HAT_UP )
    {
        /* Do up stuff here */
    }

    if ( event.jhat.value &#38; SDL_HAT_LEFT )
    {
        /* Do left stuff here */
    }

    if ( event.jhat.value &#38; SDL_HAT_RIGHTDOWN )
    {
        /* Do right and down together stuff here */
    }
    break;</PRE
></DIV
><P
>In addition to the queries for number of joysticks on the system and their names there are additional functions to query the capabilities of attached joysticks:
<P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
><A
HREF="sdljoysticknumaxes.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickNumAxes</TT
></A
></TD
><TD
>Returns the number of joysitck axes</TD
></TR
><TR
><TD
><A
HREF="sdljoysticknumbuttons.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickNumButtons</TT
></A
></TD
><TD
>Returns the number of joysitck buttons</TD
></TR
><TR
><TD
><A
HREF="sdljoysticknumballs.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickNumBalls</TT
></A
></TD
><TD
>Returns the number of joysitck balls</TD
></TR
><TR
><TD
><A
HREF="sdljoysticknumhats.html"
><TT
CLASS="FUNCTION"
>SDL_JoystickNumHats</TT
></A
></TD
><TD
>Returns the number of joysitck hats</TD
></TR
></TBODY
></TABLE
><P
></P
>

To use these functions we just have to pass in the joystick structure we got when we opened the joystick. For Example:</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN265"
></A
><P
><B
>Example 3-9. Querying Joystick Characteristics</B
></P
><PRE
CLASS="PROGRAMLISTING"
>    int number_of_buttons;
    SDL_Joystick *joystick;

    joystick = SDL_JoystickOpen(0);
    number_of_buttons = SDL_JoystickNumButtons(joystick);</PRE
></DIV
><P
>This block of code would get the number of buttons on the first joystick in the system.	</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="guidevideoopengl.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="guideinputkeyboard.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Using OpenGL With SDL</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="guide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Handling the Keyboard</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>Input handling</TITLE
	5	><META
	6	NAME="GENERATOR"
	7	CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
	8	"><LINK
	9	REL="HOME"
	10	TITLE="SDL Library Documentation"
	11	HREF="index.html"><LINK
	12	REL="UP"
	13	TITLE="SDL Guide"
	14	HREF="guide.html"><LINK
	15	REL="PREVIOUS"
	16	TITLE="Using OpenGL With SDL"
	17	HREF="guidevideoopengl.html"><LINK
	18	REL="NEXT"
	19	TITLE="Handling the Keyboard"
	20	HREF="guideinputkeyboard.html"></HEAD
	21	><BODY
	22	CLASS="CHAPTER"
	23	BGCOLOR="#FFF8DC"
	24	TEXT="#000000"
	25	LINK="#0000ee"
	26	VLINK="#551a8b"
	27	ALINK="#ff0000"
	28	><DIV
	29	CLASS="NAVHEADER"
	30	><TABLE
	31	SUMMARY="Header navigation table"
	32	WIDTH="100%"
	33	BORDER="0"
	34	CELLPADDING="0"
	35	CELLSPACING="0"
	36	><TR
	37	><TH
	38	COLSPAN="3"
	39	ALIGN="center"
	40	>SDL Library Documentation</TH
	41	></TR
	42	><TR
	43	><TD
	44	WIDTH="10%"
	45	ALIGN="left"
	46	VALIGN="bottom"
	47	><A
	48	HREF="guidevideoopengl.html"
	49	ACCESSKEY="P"
	50	>Prev</A
	51	></TD
	52	><TD
	53	WIDTH="80%"
	54	ALIGN="center"
	55	VALIGN="bottom"
	56	></TD
	57	><TD
	58	WIDTH="10%"
	59	ALIGN="right"
	60	VALIGN="bottom"
	61	><A
	62	HREF="guideinputkeyboard.html"
	63	ACCESSKEY="N"
	64	>Next</A
65	></TD
66	></TR
67	></TABLE
68	><HR
69	ALIGN="LEFT"
70	WIDTH="100%"></DIV
71	><DIV
72	CLASS="CHAPTER"
73	><H1
74	><A
75	NAME="GUIDEINPUT"
76	></A
77	>Chapter 3. Input handling</H1
78	><DIV
79	CLASS="TOC"
80	><DL
81	><DT
82	><B
83	>Table of Contents</B
84	></DT
85	><DT
86	><A
87	HREF="guideinput.html#GUIDEINPUTJOYSTICK"
88	>Handling Joysticks</A
89	></DT
90	><DT
91	><A
92	HREF="guideinputkeyboard.html"
93	>Handling the Keyboard</A
94	></DT
95	></DL
96	></DIV
97	><DIV
98	CLASS="SECT1"
99	><H1
100	CLASS="SECT1"
101	><A
102	NAME="GUIDEINPUTJOYSTICK"
103	></A
104	>Handling Joysticks</H1
105	><DIV
106	CLASS="SECT2"
107	><H2
108	CLASS="SECT2"
109	><A
110	NAME="AEN135"
111	></A
112	>Initialization</H2
113	><P
114	>The first step in using a joystick in a SDL program is to initialize the Joystick subsystems of SDL. This done by passing the <TT
115	CLASS="LITERAL"
116	>SDL_INIT_JOYSTICK</TT
117	> flag to <A
118	HREF="sdlinit.html"
119	><TT
120	CLASS="FUNCTION"
121	>SDL_Init</TT
122	></A
123	>. The joystick flag will usually be used in conjunction with other flags (like the video flag) because the joystick is usually used to control something.</P
124	><DIV
125	CLASS="EXAMPLE"
126	><A
127	NAME="AEN141"
128	></A
129	><P
130	><B
131	>Example 3-1. Initializing SDL with Joystick Support</B
132	></P
133	><PRE
134	CLASS="PROGRAMLISTING"
135	> if (SDL_Init( SDL_INIT_VIDEO \| SDL_INIT_JOYSTICK ) < 0)
136	{
137	fprintf(stderr, "Couldn't initialize SDL: %s\n", SDL_GetError());
138	exit(1);
139	}</PRE
140	></DIV
141	><P
142	>This will attempt to start SDL with both the video and the joystick subsystems activated.</P
143	></DIV
144	><DIV
145	CLASS="SECT2"
146	><H2
147	CLASS="SECT2"
148	><A
149	NAME="AEN145"
150	></A
151	>Querying</H2
152	><P
153	>If we have reached this point then we can safely assume that the SDL library has been initialized and that the Joystick subsystem is active. We can now call some video and/or sound functions to get things going before we need the joystick. Eventually we have to make sure that there is actually a joystick to work with. It's wise to always check even if you know a joystick will be present on the system because it can also help detect when the joystick is unplugged. The function used to check for joysticks is <A
154	HREF="sdlnumjoysticks.html"
155	><TT
156	CLASS="FUNCTION"
157	>SDL_NumJoysticks</TT
158	></A
159	>.</P
160	><P
161	>This function simply returns the number of joysticks available on the system. If it is at least one then we are in good shape. The next step is to determine which joystick the user wants to use. If the number of joysticks available is only one then it is safe to assume that one joystick is the one the user wants to use. SDL has a function to get the name of the joysticks as assigned by the operations system and that function is <A
162	HREF="sdljoystickname.html"
163	><TT
164	CLASS="FUNCTION"
165	>SDL_JoystickName</TT
166	></A
167	>. The joystick is specified by an index where 0 is the first joystick and the last joystick is the number returned by <TT
168	CLASS="FUNCTION"
169	>SDL_NumJoysticks</TT
170	> - 1. In the demonstration a list of all available joysticks is printed to stdout.</P
171	><DIV
172	CLASS="EXAMPLE"
173	><A
174	NAME="AEN154"
175	></A
176	><P
177	><B
178	>Example 3-2. Querying the Number of Available Joysticks</B
179	></P
180	><PRE
181	CLASS="PROGRAMLISTING"
182	> printf("%i joysticks were found.\n\n", SDL_NumJoysticks() );
183	printf("The names of the joysticks are:\n");
184
185	for( i=0; i < SDL_NumJoysticks(); i++ )
186	{
187	printf(" %s\n", SDL_JoystickName(i));
188	}</PRE
189	></DIV
190	></DIV
191	><DIV
192	CLASS="SECT2"
193	><H2
194	CLASS="SECT2"
195	><A
196	NAME="AEN157"
197	></A
198	>Opening a Joystick and Receiving Joystick Events</H2
199	><P
200	>SDL's event driven architecture makes working with joysticks a snap. Joysticks can trigger 4 different types of events:
201	<P
202	></P
203	><TABLE
204	BORDER="0"
205	><TBODY
206	><TR
207	><TD
208	><A
209	HREF="sdljoyaxisevent.html"
210	><SPAN
211	CLASS="STRUCTNAME"
212	>SDL_JoyAxisEvent</SPAN
213	></A
214	></TD
215	><TD
216	>Occurs when an axis changes</TD
217	></TR
218	><TR
219	><TD
220	><A
221	HREF="sdljoyballevent.html"
222	><SPAN
223	CLASS="STRUCTNAME"
224	>SDL_JoyBallEvent</SPAN
225	></A
226	></TD
227	><TD
228	>Occurs when a joystick trackball's position changes</TD
229	></TR
230	><TR
231	><TD
232	><A
233	HREF="sdljoyhatevent.html"
234	><SPAN
235	CLASS="STRUCTNAME"
236	>SDL_JoyHatEvent</SPAN
237	></A
238	></TD
239	><TD
240	>Occurs when a hat's position changes</TD
241	></TR
242	><TR
243	><TD
244	><A
245	HREF="sdljoybuttonevent.html"
246	><SPAN
247	CLASS="STRUCTNAME"
248	>SDL_JoyButtonEvent</SPAN
249	></A
250	></TD
251	><TD
252	>Occurs when a button is pressed or released</TD
253	></TR
254	></TBODY
255	></TABLE
256	><P
257	></P
258	></P
259	><P
260	>Events are received from all joysticks opened. The first thing that needs to be done in order to receive joystick events is to call <A
261	HREF="sdljoystickeventstate.html"
262	><TT
263	CLASS="FUNCTION"
264	>SDL_JoystickEventState</TT
265	></A
266	> with the <TT
267	CLASS="LITERAL"
268	>SDL_ENABLE</TT
269	> flag. Next you must open the joysticks that you want to receive envents from. This is done with the <A
270	HREF="sdljoystickopen.html"
271	><TT
272	CLASS="FUNCTION"
273	>SDL_JoystickOpen</TT
274	></A
275	> function. For the example we are only interested in events from the first joystick on the system, regardless of what it may be. To receive events from it we would do this:</P
276	><DIV
277	CLASS="EXAMPLE"
278	><A
279	NAME="AEN183"
280	></A
281	><P
282	><B
283	>Example 3-3. Opening a Joystick</B
284	></P
285	><PRE
286	CLASS="PROGRAMLISTING"
287	> SDL_Joystick *joystick;
288
289	SDL_JoystickEventState(SDL_ENABLE);
290	joystick = SDL_JoystickOpen(0);</PRE
291	></DIV
292	><P
293	>If we wanted to receive events for other joysticks we would open them with calls to <TT
294	CLASS="FUNCTION"
295	>SDL_JoystickOpen</TT
296	> just like we opened joystick 0, except we would store the <SPAN
297	CLASS="STRUCTNAME"
298	>SDL_Joystick</SPAN
299	> structure they return in a different pointer. We only need the joystick pointer when we are querying the joysticks or when we are closing the joystick.</P
300	><P
301	>Up to this point all the code we have is used just to initialize the joysticks in order to read values at run time. All we need now is an event loop, which is something that all SDL programs should have anyway to receive the systems quit events. We must now add code to check the event loop for at least some of the above mentioned events. Let's assume our event loop looks like this:
302	<PRE
303	CLASS="PROGRAMLISTING"
304	> SDL_Event event;
305	/* Other initializtion code goes here */
306
307	/* Start main game loop here */
308
309	while(SDL_PollEvent(&event))
310	{
311	switch(event.type)
312	{
313	case SDL_KEYDOWN:
314	/* handle keyboard stuff here */
315	break;
316
317	case SDL_QUIT:
318	/* Set whatever flags are necessary to */
319	/* end the main game loop here */
320	break;
321	}
322	}
323
324	/* End loop here */</PRE
325	>
326	To handle Joystick events we merely add cases for them, first we'll add axis handling code. Axis checks can get kinda of tricky because alot of the joystick events received are junk. Joystick axis have a tendency to vary just a little between polling due to the way they are designed. To compensate for this you have to set a threshold for changes and ignore the events that have'nt exceeded the threshold. 10% is usually a good threshold value. This sounds a lot more complicated than it is. Here is the Axis event handler:</P
327	><DIV
328	CLASS="EXAMPLE"
329	><A
330	NAME="AEN191"
331	></A
332	><P
333	><B
334	>Example 3-4. Joystick Axis Events</B
335	></P
336	><PRE
337	CLASS="PROGRAMLISTING"
338	> case SDL_JOYAXISMOTION: /* Handle Joystick Motion */
339	if ( ( event.jaxis.value < -3200 ) \|\| (event.jaxis.value > 3200 ) )
340	{
341	/* code goes here */
342	}
343	break;</PRE
344	></DIV
345	><P
346	>Another trick with axis events is that up-down and left-right movement are two different sets of axes. The most important axis is axis 0 (left-right) and axis 1 (up-down). To handle them seperatly in the code we do the following:</P
347	><DIV
348	CLASS="EXAMPLE"
349	><A
350	NAME="AEN195"
351	></A
352	><P
353	><B
354	>Example 3-5. More Joystick Axis Events</B
355	></P
356	><PRE
357	CLASS="PROGRAMLISTING"
358	> case SDL_JOYAXISMOTION: /* Handle Joystick Motion */
359	if ( ( event.jaxis.value < -3200 ) \|\| (event.jaxis.value > 3200 ) )
360	{
361	if( event.jaxis.axis == 0)
362	{
363	/* Left-right movement code goes here */
364	}
365
366	if( event.jaxis.axis == 1)
367	{
368	/* Up-Down movement code goes here */
369	}
370	}
371	break;</PRE
372	></DIV
373	><P
374	>Ideally the code here should use <TT
375	CLASS="STRUCTFIELD"
376	><I
377	>event.jaxis.value</I
378	></TT
379	> to scale something. For example lets assume you are using the joystick to control the movement of a spaceship. If the user is using an analog joystick and they push the stick a little bit they expect to move less than if they pushed it a lot. Designing your code for this situation is preferred because it makes the experience for users of analog controls better and remains the same for users of digital controls.</P
380	><P
381	>If your joystick has any additional axis then they may be used for other sticks or throttle controls and those axis return values too just with different <TT
382	CLASS="STRUCTFIELD"
383	><I
384	>event.jaxis.axis</I
385	></TT
386	> values.</P
387	><P
388	>Button handling is simple compared to the axis checking.</P
389	><DIV
390	CLASS="EXAMPLE"
391	><A
392	NAME="AEN203"
393	></A
394	><P
395	><B
396	>Example 3-6. Joystick Button Events</B
397	></P
398	><PRE
399	CLASS="PROGRAMLISTING"
400	> case SDL_JOYBUTTONDOWN: /* Handle Joystick Button Presses */
401	if ( event.jbutton.button == 0 )
402	{
403	/* code goes here */
404	}
405	break;</PRE
406	></DIV
407	><P
408	>Button checks are simpler than axis checks because a button can only be pressed or not pressed. The <TT
409	CLASS="LITERAL"
410	>SDL_JOYBUTTONDOWN</TT
411	> event is triggered when a button is pressed and the <TT
412	CLASS="LITERAL"
413	>SDL_JOYBUTTONUP</TT
414	> event is fired when a button is released. We do have to know what button was pressed though, that is done by reading the <TT
415	CLASS="STRUCTFIELD"
416	><I
417	>event.jbutton.button</I
418	></TT
419	> field.</P
420	><P
421	>Lastly when we are through using our joysticks we should close them with a call to <A
422	HREF="sdljoystickclose.html"
423	><TT
424	CLASS="FUNCTION"
425	>SDL_JoystickClose</TT
426	></A
427	>. To close our opened joystick 0 we would do this at the end of our program:
428	<PRE
429	CLASS="PROGRAMLISTING"
430	> SDL_JoystickClose(joystick);</PRE
431	></P
432	></DIV
433	><DIV
434	CLASS="SECT2"
435	><H2
436	CLASS="SECT2"
437	><A
438	NAME="AEN214"
439	></A
440	>Advanced Joystick Functions</H2
441	><P
442	>That takes care of the controls that you can count on being on every joystick under the sun, but there are a few extra things that SDL can support. Joyballs are next on our list, they are alot like axis with a few minor differences. Joyballs store relative changes unlike the the absolute postion stored in a axis event. Also one trackball event contains both the change in x and they change in y. Our case for it is as follows:</P
443	><DIV
444	CLASS="EXAMPLE"
445	><A
446	NAME="AEN217"
447	></A
448	><P
449	><B
450	>Example 3-7. Joystick Ball Events</B
451	></P
452	><PRE
453	CLASS="PROGRAMLISTING"
454	> case SDL_JOYBALLMOTION: /* Handle Joyball Motion */
455	if( event.jball.ball == 0 )
456	{
457	/* ball handling */
458	}
459	break;</PRE
460	></DIV
461	><P
462	>The above checks the first joyball on the joystick. The change in position will be stored in <TT
463	CLASS="STRUCTFIELD"
464	><I
465	>event.jball.xrel</I
466	></TT
467	> and <TT
468	CLASS="STRUCTFIELD"
469	><I
470	>event.jball.yrel</I
471	></TT
472	>.</P
473	><P
474	>Finally we have the hat event. Hats report only the direction they are pushed in. We check hat's position with the bitmasks:
475
476	<P
477	></P
478	><TABLE
479	BORDER="0"
480	><TBODY
481	><TR
482	><TD
483	><TT
484	CLASS="LITERAL"
485	>SDL_HAT_CENTERED</TT
486	></TD
487	></TR
488	><TR
489	><TD
490	><TT
491	CLASS="LITERAL"
492	>SDL_HAT_UP</TT
493	></TD
494	></TR
495	><TR
496	><TD
497	><TT
498	CLASS="LITERAL"
499	>SDL_HAT_RIGHT</TT
500	></TD
501	></TR
502	><TR
503	><TD
504	><TT
505	CLASS="LITERAL"
506	>SDL_HAT_DOWN</TT
507	></TD
508	></TR
509	><TR
510	><TD
511	><TT
512	CLASS="LITERAL"
513	>SDL_HAT_LEFT</TT
514	></TD
515	></TR
516	></TBODY
517	></TABLE
518	><P
519	></P
520	>
521
522	Also there are some predefined combinations of the above:
523	<P
524	></P
525	><TABLE
526	BORDER="0"
527	><TBODY
528	><TR
529	><TD
530	><TT
531	CLASS="LITERAL"
532	>SDL_HAT_RIGHTUP</TT
533	></TD
534	></TR
535	><TR
536	><TD
537	><TT
538	CLASS="LITERAL"
539	>SDL_HAT_RIGHTDOWN</TT
540	></TD
541	></TR
542	><TR
543	><TD
544	><TT
545	CLASS="LITERAL"
546	>SDL_HAT_LEFTUP</TT
547	></TD
548	></TR
549	><TR
550	><TD
551	><TT
552	CLASS="LITERAL"
553	>SDL_HAT_LEFTDOWN</TT
554	></TD
555	></TR
556	></TBODY
557	></TABLE
558	><P
559	></P
560	>
561
562	Our case for the hat may resemble the following:</P
563	><DIV
564	CLASS="EXAMPLE"
565	><A
566	NAME="AEN244"
567	></A
568	><P
569	><B
570	>Example 3-8. Joystick Hat Events</B
571	></P
572	><PRE
573	CLASS="PROGRAMLISTING"
574	> case SDL_JOYHATMOTION: /* Handle Hat Motion */
575	if ( event.jhat.value & SDL_HAT_UP )
576	{
577	/* Do up stuff here */
578	}
579
580	if ( event.jhat.value & SDL_HAT_LEFT )
581	{
582	/* Do left stuff here */
583	}
584
585	if ( event.jhat.value & SDL_HAT_RIGHTDOWN )
586	{
587	/* Do right and down together stuff here */
588	}
589	break;</PRE
590	></DIV
591	><P
592	>In addition to the queries for number of joysticks on the system and their names there are additional functions to query the capabilities of attached joysticks:
593	<P
594	></P
595	><TABLE
596	BORDER="0"
597	><TBODY
598	><TR
599	><TD
600	><A
601	HREF="sdljoysticknumaxes.html"
602	><TT
603	CLASS="FUNCTION"
604	>SDL_JoystickNumAxes</TT
605	></A
606	></TD
607	><TD
608	>Returns the number of joysitck axes</TD
609	></TR
610	><TR
611	><TD
612	><A
613	HREF="sdljoysticknumbuttons.html"
614	><TT
615	CLASS="FUNCTION"
616	>SDL_JoystickNumButtons</TT
617	></A
618	></TD
619	><TD
620	>Returns the number of joysitck buttons</TD
621	></TR
622	><TR
623	><TD
624	><A
625	HREF="sdljoysticknumballs.html"
626	><TT
627	CLASS="FUNCTION"
628	>SDL_JoystickNumBalls</TT
629	></A
630	></TD
631	><TD
632	>Returns the number of joysitck balls</TD
633	></TR
634	><TR
635	><TD
636	><A
637	HREF="sdljoysticknumhats.html"
638	><TT
639	CLASS="FUNCTION"
640	>SDL_JoystickNumHats</TT
641	></A
642	></TD
643	><TD
644	>Returns the number of joysitck hats</TD
645	></TR
646	></TBODY
647	></TABLE
648	><P
649	></P
650	>
651
652	To use these functions we just have to pass in the joystick structure we got when we opened the joystick. For Example:</P
653	><DIV
654	CLASS="EXAMPLE"
655	><A
656	NAME="AEN265"
657	></A
658	><P
659	><B
660	>Example 3-9. Querying Joystick Characteristics</B
661	></P
662	><PRE
663	CLASS="PROGRAMLISTING"
664	> int number_of_buttons;
665	SDL_Joystick *joystick;
666
667	joystick = SDL_JoystickOpen(0);
668	number_of_buttons = SDL_JoystickNumButtons(joystick);</PRE
669	></DIV
670	><P
671	>This block of code would get the number of buttons on the first joystick in the system. </P
672	></DIV
673	></DIV
674	></DIV
675	><DIV
676	CLASS="NAVFOOTER"
677	><HR
678	ALIGN="LEFT"
679	WIDTH="100%"><TABLE
680	SUMMARY="Footer navigation table"
681	WIDTH="100%"
682	BORDER="0"
683	CELLPADDING="0"
684	CELLSPACING="0"
685	><TR
686	><TD
687	WIDTH="33%"
688	ALIGN="left"
689	VALIGN="top"
690	><A
691	HREF="guidevideoopengl.html"
692	ACCESSKEY="P"
693	>Prev</A
694	></TD
695	><TD
696	WIDTH="34%"
697	ALIGN="center"
698	VALIGN="top"
699	><A
700	HREF="index.html"
701	ACCESSKEY="H"
702	>Home</A
703	></TD
704	><TD
705	WIDTH="33%"
706	ALIGN="right"
707	VALIGN="top"
708	><A
709	HREF="guideinputkeyboard.html"
710	ACCESSKEY="N"
711	>Next</A
712	></TD
713	></TR
714	><TR
715	><TD
716	WIDTH="33%"
717	ALIGN="left"
718	VALIGN="top"
719	>Using OpenGL With SDL</TD
720	><TD
721	WIDTH="34%"
722	ALIGN="center"
723	VALIGN="top"
724	><A
725	HREF="guide.html"
726	ACCESSKEY="U"
727	>Up</A
728	></TD
729	><TD
730	WIDTH="33%"
731	ALIGN="right"
732	VALIGN="top"
733	>Handling the Keyboard</TD
734	></TR
735	></TABLE
736	></DIV
737	></BODY
738	></HTML
739	>