1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
4<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
5<base target="main">
6<title>KPAD API Introduction</title>
7</head>
8
9<body>
10
11
12
13<h1>KPAD API Description</h1>
14
15<hr>
16
17<h2>Introduction</h2>
18<p>This manual was written to support <font color="ff0000">UI Tool Version 3</font> and <font color="ff0000">UI Tool Version 4</font>.</p>
19
20<p>
21The <font color="ff0000">KPAD library</font> is a high-level library located in the upper part of the WPAD library. In contrast to using the WPAD library directly, the KPAD library can obtain coordinates where the Wii Remote is pointing more easily. It also provides features such as reducing the effects of hand tremor and adjusting the sensitivity of the Wii Remote. Not only can controller data for the Wii Remote Control be obtained, but controller data can also be obtained for a Nunchuk and the Nintendo GameCube standard controller.
22</p>
23
24<p>
25Samples are provided to test the functionality of the KPAD library in <code>$(REVOLUTION_SDK_ROOT)/build/demos/kpaddemo/</code> (for UI Tool Version 4) and in <code>$(REVOLUTION_SDK_ROOT)/build/demos/kpadEmudemo/</code> (for UI Tool Version 3). When using these samples, we recommend placing the Wii Remote Control and the Sensor Bar at least 1.5 meters apart (the samples may not function well at a distance of 1.0 meter).
26</p>
27
28<p>
29The KPAD library is in the following path.
30<ul>
31<li><CODE>$(REVOLUTION_SDK_ROOT)/RVL[0]/lib/kpad[D].a   </CODE>  (for UI Tool Version 4)
32<li><CODE>$(REVOLUTION_SDK_ROOT)/RVL[0]/lib/kpadEmu[D].a</CODE>  (for UI Tool Version 3)
33</ul>
34</p>
35
36<p>
37API functions declarations are in the <code>$(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h</code> header file.
38</p>
39
40<h2>Process Flow</h2>
41<h3>KPAD Initialization</h3>
42<p>
43Initialization of the KPAD library occurs by calling the <a href="./KPADInit.html">KPADInit</a> function. <font color="ff0000">For the KPAD library corresponding to UI Tool Version 4, <a href="../wpad/WPADRegisterAllocator.html">WPADRegisterAllocator</a> must be called to register the allocator function used to allocate and deallocate memory for the WPAD library prior to calling <a href="./KPADInit.html">KPADInit</a>.</font> After the KPAD library is initialized, it uses its autosampling feature to obtain data and update its internal buffer.
44</p>
45
46<h3>Obtaining Controller Information</h3>
47<p>
48Using the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function, the specified channel's controller information is read into a <a href="./KPADStatus.html"><code>KPADStatus</code></a> structure. When adjusting the Wii Remote Control reaction and the hand tremor reduction level, use <a href="./KPADSetPosParam.html"><code>KPADSetPosParam</code></a>, <a href="./KPADSetHoriParam.html"><code>KPADSetHoriParam</code></a>, <a href="./KPADSetDistParam.html"><code>KPADSetDistParam</code></a>, or <a href="./KPADSetAccParam.html"><code>KPADSetAccParam</code></a>. These functions can adjust the controller status obtained with <a href="./KPADRead.html"><code>KPADRead</code></a>.
49</p>
50
51<h3>Other</h3>
52<p>
53In some cases, it might be effective to call the <a href="./KPADReset.html"><code>KPADReset</code></a> function, such as during a change in scenes.
54</p>
55
56<h2>Notes</h2>
57<h3>Differences in Coordinate System</h3>
58<p>
59The coordinate system of the coordinates obtained with the KPAD library is different from that used in the WPAD library. For details, see the <a href="./KPADStatus.html"><code>KPADStatus</code></a> and <a href="./KPADStatus.html"><code>KPADEXStatus</code></a> structure pages.
60</p>
61
62<h3>Regarding Data Loss</h3>
63<p>
64<a href="./KPADRead.html">KPADRead</a> function is designed to be called once per game frame. However, if the interval between <a href="./KPADRead.html">KPADRead</a> function calls becomes too long due to, for example, a process slowdown, the ring buffer in the KPAD library may complete the cycle and result in data loss. These conditions can be sometimes improved by changing the <code>KPAD_RING_BUFS</code> macro value in <code>$(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h</code> to increase the ring buffer and by using the rebuilt KPAD library.
65</p>
66
67<h3>Unsupported APIs</h3>
68<p>
69Although APIs were provided for the UI Tool Version 3 KPAD library to get and process data from standard Nintendo GameCube controllers, in the UI Tool Version 4 KPAD library, support for these APIs is eliminated.
70</p>
71
72<H2>Revision History</H2>
73<P>
7403/01/2006 Initial version. <BR> 5/15/2006 Added to Cautions; how to avoid a data loss when the interval between the <a href="./KPADRead.html">KPADRead</a> function becomes too long.<BR> 06/19/2006 Support for UI Tool Version 4. Changed tentative product name to official name.<BR>
75</P>
76
77</body>
78</html>
79