1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META http-equiv="Content-Style-Type" content="text/css">
6<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
7<title>KPADReadEx</title>
8</head>
9
10<body>
11
12<h1>KPADReadEx</h1>
13
14<h2>Syntax</h2>
15<dl><dd><pre class="construction">
16#include &lt;revolution/kpad.h&gt;
17
18#define KPAD_READ_ERR_NONE           0
19#define KPAD_READ_ERR_NO_DATA       -1
20#define KPAD_READ_ERR_NO_CONTROLLER -2
21#define KPAD_READ_ERR_SETUP         -3
22#define KPAD_READ_ERR_LOCKED        -4
23#define KPAD_READ_ERR_INIT          -5
24
25s32 KPADReadEx( s32 chan, KPADStatus samplingBufs[], u32 length, s32 *err );
26</pre></dd></dl>
27
28<h2>Arguments</h2>
29<TABLE class="arguments" border="1" >
30  <TBODY>
31    <TR>
32      <TH>chan</TH>
33      <TD>One of the <code>WPAD_CHAN<i>n</i></code> values.</TD>
34    </TR>
35    <TR>
36      <TH>samplingBufs</TH>
37      <TD>Pointer to the <a href="./KPADStatus.html"><code>KPADStatus</code></a> structure.</TD>
38    </TR>
39    <TR>
40      <TH>length</TH>
41      <TD>Maximum number of data sets to store. If you use the <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> function, this cannot exceed <code>KPAD_RING_BUFS</code>. If you use the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function, this value cannot exceed the sum of <code>KPAD_RING_BUFS</code> and one-quarter the array length passed to the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function.</TD>
42    </TR>
43    <TR>
44      <TH>err</TH>
45      <TD>Pointer to the variable for passing the error code.</TD>
46    </TR>
47  </TBODY>
48</TABLE>
49
50<h2>Return Values</h2>
51<p>Returns the number of data sets actually stored.</p>
52
53<H2>Description</H2>
54<p>
55This function loads data of the <a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a> structure type for each controller channel. We have assumed that this function will be called for each game frame. The buffer specified by the argument stores, from newest to oldest, the data sampled from the time of the previous call to the time of the current call. (In other words, the newest data is always stored at the beginning of the buffer.) However, in the case of button information only, if the button processing method obtained using the <CODE>KPADGetButtonProcMode</CODE> function is <CODE>KPAD_BUTTON_PROC_MODE_LOOSE</CODE>, only the most recent values are accessed when the <CODE>KPADRead</CODE> or <CODE>KPADReadEx</CODE> functions are called, and those values are copied into all the current-frame sampling buffers.
56</p>
57<p>
58Note, however, that the buffer specified by <SPAN class="argument">samplingBufs</SPAN> may be used internally as a work area. Because of this, even if there is no data, the contents of the buffer might be rewritten; still, even in this case, the newest data will not change.
59</p>
60
61<p>The following error codes are passed to <SPAN class="argument">err</SPAN>:</p>
62<table border="1" class="arguments">
63  <tr>
64    <th>KPAD_READ_ERR_NONE</th>
65    <td>There is sampling data.</td>
66  </tr>
67  <tr>
68    <th>KPAD_READ_ERR_NO_DATA</th>
69    <td>No sampling data.</td>
70  </tr>
71  <tr>
72    <th>KPAD_READ_ERR_NO_CONTROLLER</th>
73    <td>The Wii Remote is not connected.</td>
74  </tr>
75  <tr>
76    <th>KPAD_READ_ERR_SETUP</th>
77    <td>WPAD library initialization is not complete.</td>
78  </tr>
79  <tr>
80    <th>KPAD_READ_ERR_LOCKED</th>
81    <td>Duplicate calls caused failure to obtain permission to process.</td>
82  </tr>
83  <tr>
84    <th>KPAD_READ_ERR_INIT</th>
85    <td>The <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> function (or the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function) has not been called.</td>
86  </tr>
87</table>
88
89<h2>See Also</h2>
90<p class="reference">
91<a href="./KPADStatus.html">KPADStatus</a>
92</p>
93
94<H2>Revision History</H2>
95<P>
962008/06/13 Revised the explanation of <SPAN class="argument">length</SPAN>. Added explanation of the differences caused by different button processing methods. Added mention that the newest data values are guaranteed protected.<br>2008/06/03 Initial version.<br>
97</P>
98
99<hr><p>CONFIDENTIAL</p></body>
100</html>