1<html> 2 3<head> 4<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> 5<meta name="ProgId" content="FrontPage.Editor.Document"> 6<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 7<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 8<base target="main"> 9<title>WPAD API Introduction</title> 10</head> 11 12<body> 13 14<h1>WPAD API Introduction</h1> 15 16<hr> 17 18<h2>Introduction</h2> 19 20<p>The Wii console communicates with its standard controller, the Wii Remote, using wireless technology in the 2.4GHz bandwidth. The Wii Remote includes a rumble motor, a pointer, a motion sensor, a speaker, a player indicator and an external expansion connector. By connecting a variety of external expansion controllers to the external expansion connector, a greater variety of user interfaces is available.</p> 21 22<h2>Library Structure</h2> 23 24<p>The WPAD library includes a higher-level library (KPAD), and is implemented as follows. The KPAD library is a high-level portion of the WPAD library which was designed so that WPAD library is easier to use within games.</p> 25 26<table border="1" width="200"> 27 <tbody> 28 <tr> 29 <td align="center" bgcolor="khaki">KPAD API</td> 30 </tr> 31 <tr> 32 <td align="center" bgcolor="palegreen">WPAD API</td> 33 </tr> 34 </tbody> 35</table> 36 37 38<h2>Initialization</h2> 39<p> 40Begin initialization of the WPAD library by calling the <a href="./WPADRegisterAllocator.html"><code>WPADRegisterAllocator</code></a> function. This registers the allocator function used to obtain work memory during the initialization process. The size of the work memory allocated by the library can be retrieved using the function <a href="WPADGetWorkMemorySize.html"><code>WPADGetWorkMemorySize</code></a>. 41</p> 42<p> 43Then call the <a href="WPADInit.html"><code>WPADInit</code></a> function to initialize the WPAD library. Because it will take time to initialize the WPAD library, call the <a href="./WPADGetStatus.html"><code>WPADGetStatus</code></a> function periodically and check when initialization is complete. 44</p> 45 46<h2>Controller Registration</h2> 47<p> 48To enable communication between the Wii console and the Wii Remote, you must first register the Wii Remote to the Wii console. Registration occurs automatically when the SYNCHRO button on the front of the Wii console and the SYNCHRO button within the battery cover on the Wii Remote are pressed. Game applications, by calling the <a href="WPADSetSyncDeviceCallback.html"><code>WPADSetSyncDeviceCallback</code></a> function and setting a user callback function in advance, can determine whether the SYNCHRO button on the Wii console was pressed. When a callback function is set, registration will not occur automatically, even when the SYNCHRO button is pressed; begin registration by calling the <a href="WPADStartSyncDevice.html"><code>WPADStartSyncDevice</code></a> function. In addition, the registered callback function is called again after registration is complete, and you can determine how many Wii Remotes are registered. 49</p> 50 51<h2>Controller Removal</h2> 52<p> 53If the SYNCHRO button on the Wii console is pressed for 10 seconds or more, all information on the Wii Remote Controls registered to the Wii console will be automatically deleted. The game application can get this event by calling the <a href="WPADSetClearDeviceCallback.html"><code>WPADSetClearDeviceCallback</code></a> function and setting a user callback function in advance. When a callback function is set, information on the remote controls is not automatically deleted; this can be started by calling the <a href="WPADStartClearDevice.html"><code>WPADStartClearDevice</code></a> function. In addition, the registered callback function is called again when the deletion is complete. 54</p> 55 56<h2>Controller Status Confirmation</h2> 57<p> 58The game application can call the <a href="./WPADProbe.html"><code>WPADProbe</code></a> function to get the connection status of each number's controller. If an external expansion controller was inserted into a Wii Remote, this function also returns the current type of the external expansion controller. Since this function confirms the insertion and removal of an external expansion controller, we recommend that the game application call this function at least once within the main loop. In addition, you can determine if a controller has been connected or disconnected by using the <a href="./WPADSetConnectCallback.html"><code>WPADSetConnectCallback</code></a> function to register a callback function in advance. Also, the insertion and removal of an external expansion controller can be detected by registering a callback function in advance using the <a href="./WPADSetExtensionCallback.html"><code>WPADSetExtensionCallback</code></a> function. 59</p> 60<p> 61In addition, the <a href="./WPADGetInfo.html"><code>WPADGetInfo(Async)</code></a> function can be called to get the current controller information (remaining battery power, player indicator status, etc.). 62</p> 63 64<h2>Controller Controls</h2> 65<p> 66The game application can perform a variety of controls with the Wii Remote, including changing the format of received data, getting the remote control's status, and starting and stopping the pointer. However, all of these controls must be handled exclusively. The WPAD library maintains separate command queues internally for each channel, and requests from the game application are managed by these queues. When the WPAD library cannot add a new request, <code>WPAD_ERR_BUSY</code> is returned; when this error is returned to the game application, the request should be issued again after waiting for some time. 67</p> 68<p> 69In addition, be aware that the WPAD library uses these queues internally immediately after inserting/removing or connecting an external expansion controller. 70</p> 71 72<h2>Specifying the Received Data Format</h2> 73<p> 74The Wii Remote can use its buttons, pointer, and motion sensor. In addition, external expansion controller input can be used by inserting an external expansion controller like a Nunchuk device. However, not all data can be sent because of the wireless specifications. Therefore, the game application must call the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function to select the format for the controller information according to its application. The following formats for controller information are available. 75</p> 76 77<table border="1" cellpadding="3" cellspacing="0.1"> 78 <tbody> 79 <tr> 80<td><code>WPAD_FMT_CORE</code></td> 81<td>Wii Remote buttons only</td> 82 </tr> 83 <tr> 84<td><code>WPAD_FMT_CORE_ACC</code></td> 85<td>Wii Remote buttons and motion sensor</td> 86 </tr> 87 <tr> 88<td><code>WPAD_FMT_CORE_ACC_DPD</code></td> 89<td>Wii Remote buttons, motion sensor, and pointer (coordinate data and size)</td> 90 </tr> 91 <tr> 92<td><code>WPAD_FMT_FREESTYLE</code></td> 93<td>Wii Remote buttons and the Nunchuk device</td> 94 </tr> 95 <tr> 96<td><code>WPAD_FMT_FREESTYLE_ACC</code></td> 97<td>Wii Remote buttons, motion sensor, and the Nunchuk device</td> 98 </tr> 99 <tr> 100<td><code>WPAD_FMT_FREESTYLE_ACC_DPD</code></td> 101<td>Wii Remote buttons, motion sensor, pointer (coordinate data), and the Nunchuk device</td> 102 </tr> 103 <tr> 104<td><code>WPAD_FMT_CLASSIC</code></td> 105<td>Wii Remote buttons and the Classic controller</td> 106 </tr> 107 <tr> 108<td><code>WPAD_FMT_CLASSIC_ACC</code></td> 109<td>Wii Remote buttons, motion sensor, and the Classic controller</td> 110 </tr> 111 <tr> 112<td><code>WPAD_FMT_CLASSIC_ACC_DPD</code></td> 113<td>Wii Remote buttons, motion sensor, pointer (coordinate data), and the Classic controller</td> 114 </tr> 115 </tbody> 116</table> 117 118<font color="red"><p> 119Note: When specifying, among the above formats (a format that uses the pointer), call the <a href="./WPADControlDpd.html"><code>WPADControlDpd</code></a> function to launch the pointer before calling the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function. 120</p></font> 121<h2>Obtaining Controller Information</h2> 122<p> 123There are two ways to obtain the controller information. 124<ul> 125<li>Obtain only the most recent controller information.</li> 126</ul> 127<blockquote> 128Use the <a href="./WPADRead.html"><code>WPADRead</code></a> function to get the most recent controller information for the Wii Remote on the specified channel. 129</blockquote> 130 131<ul> 132<li>Periodically store (auto-sampling) controller information to the buffer provided by the application.</li> 133</ul> 134<blockquote> 135The buffer for periodically storing controller information is set with the <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> function. Buffers are used internally as ring buffers. The buffer index that stored the most recent controller information can be obtained with the <a href="./WPADGetLatestIndexInBuf.html"><code>WPADGetLatestIndexInBuf</code></a> function. 136</blockquote> 137<p> 138<a href="./WPADRead.html"><code>WPADRead</code></a> and <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> can be used together. 139</p> 140<p> 141The type of controller information that can be obtained with the <a href="./WPADRead.html"><code>WPADRead</code></a> and <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> functions is recorded in a structure type corresponding to the data format specified by the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function. For information on controller types, data formats, and corresponding structure types, see the section on the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function. If the data is recorded in a structure type that does not match the data format, it might not be possible to get valid data. 142</p> 143<p> 144The callback function to call every time data is received from a Wii Remote at a specified channel can be registered with the <a href="./WPADSetSamplingCallback.html"><code>WPADSetSamplingCallback</code></a> function.</li> 145</p> 146 147<h2>Inserting/Removing External Expansion Controllers</h2> 148<p> 149A variety of external expansion controllers can be inserted into the external expansion connector on the Wii Remote even while the Wii Remote is communicating. The game application can detect an insertion/removal of an external expansion controller by using polling with the <a href="./WPADProbe.html"><code>WPADProbe</code></a> function or by registering a callback function in advance with the <a href="./WPADSetExtensionCallback.html"><code>WPADSetExtensionCallback</code></a> function. If an external expansion controller is inserted/removed during communications, the Wii Remote stops sending controller information. Therefore, when an insertion or a removal is detected, reset the data format for controller information based on that status using the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function. Once settings are complete, controller information will be sent from the Wii Remote. 150</p> 151 152<h2>Rumble Motor Controls</h2> 153<p> 154You can use <a href="./WPADControlMotor.html"><code>WPADControlMotor</code></a> function to control the vibration of the Wii Remote for the specified channel. In addition, the <a href="./WPADStartMotor.html"><code>WPADStartMotor</code></a> and <a href="./WPADStartMotor.html"><code>WPADStopMotor</code></a> functions are available as macro functions. You can use <a href="./WPADEnableMotor.html"><code>WPADEnableMotor</code></a> function to turn ON or OFF the Rumble Feature of the Wii Remote for the specified channel. The current state of the Rumble Feature can be retrieved using the function <a href="./WPADIsMotorEnabled.html"><code>WPADIsMotorEnabled</code></a>. In addition, the configured state can be saved for the Wii Remote using the function <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a>. 155</p> 156 157<h2>Speaker Controls</h2> 158<p> 159You can use <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> function to control the speaker of the Wii Remote on the specified channel. Activate the speaker using the function <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a>. Once activated, audio can be output from the speaker by sending audio data using the <a href="./WPADSendStreamData.html"><code>WPADSendStreamData</code></a> function. Due to audio specifications of the audio processor of the Wii Remote, 20 bytes of audio data must be sent three times every 20 ms in order to achieve correct audio playback. 160</p> 161<p> 162You can use <a href="./WPADSetSpeakerVolume.html"><code>WPADSetSpeakerVolume</code></a> function to set the speaker of the Wii Remote on the specified channel. Note, however, that audio may be interrupted if the volume is changed during playback. Furthermore, the configured volume can be saved for the Wii Remote using the function <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a>. 163</p> 164 165<h2>Configuring Controller Features</h2> 166<p> 167ON/OFF setting of the Rumble Feature and the speaker volume setting can be saved for each Wii Remote. Values set using the <a href="./WPADEnableMotor.html"><code>WPADEnableMotor</code></a> and <a href="./WPADSetSpeakerVolume.html"><code>WPADSetSpeakerVolume</code></a> functions can be saved for the Wii Remote using the <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a> function. 168</p> 169 170<h2>Cautions for Using Wireless LAN</h2> 171<p> 172As the Wii console and the Wii Remote Control communicate using a 2.4GHz bandwidth, the use of a wireless LAN running on the same 2.4GHz bandwidth may cause interference with the Wii device, which can prevent proper communications. As a result, when launching a wireless LAN, call the <a href="WPADSetDisableChannel.html"><code>WPADSetDisableChannel</code></a> function so as not to use the same frequency bandwidths used for the wireless LAN. 173</p> 174 175<h2>Revision History</h2> 176<p> 17708/01/2005 Initial version.<br> 08/30/2005 Modified description of buttons in Introduction; added a bug report<br> 09/27/2005 Changed abbreviation to DPD. Deleted description of hardware in the Introduction section<br> 11/01/2005 Added caution about SI to reflect the change of the interface from EXI to SI. Added links to functions. Added KPAD library introduction text. Added bug report.<br>11/09/2005 Corrected warnings about use of GameCube standard controller. Changed description of PAD library treatment in GameCube SDK. Added bug report.<br>11/10/2005 Added description of DPD module's hardware bug.<BR> 06/19/2006 Deleted the object size restriction from the cautions specific to UI tools.<br> 07/04/2006 Added speaker-related information.<br> 178</p> 179</li> 180</ul> 181 182</body></html>