1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 5 <meta http-equiv="Content-Style-Type" content="text/css" /> 6 <link rel="stylesheet" href="../../../../css/manpage.css" type="text/css" /> 7 <style type="text/css"><!-- 8 span.static_style 9 { 10 font-size : 8pt; 11 color : white; 12 font-weight : bold; 13 background : #44f; 14 border-left : solid 1px #aaf; 15 border-top : solid 1px #aaf; 16 border-right : solid 1px #00c; 17 border-bottom : solid 1px #00c; 18 padding-left : 2px; 19 padding-right : 2px; 20 } 21 span.virtual_style 22 { 23 font-size : 8pt; 24 color : white; 25 font-weight : bold; 26 background : #0a0; 27 border-left : solid 1px #0f0; 28 border-top : solid 1px #0f0; 29 border-right : solid 1px #060; 30 border-bottom : solid 1px #060; 31 padding-left : 2px; 32 padding-right : 2px; 33 } 34 span.protected_style 35 { 36 font-size : 8pt; 37 color : white; 38 font-weight : bold; 39 background : #444; 40 border-left : solid 1px #ccc; 41 border-top : solid 1px #ccc; 42 border-right : solid 1px #222; 43 border-bottom : solid 1px #222; 44 padding-left : 2px; 45 padding-right : 2px; 46 } 47 --></style> 48<title>nn::hid::CTR::GyroscopeReader</title> 49 </head> 50 <body> 51<h1><CODE><a href="../../../../nn/Overview.html">nn</a>::<a href="../../../../nn/hid/Overview.html">hid</a>::<a href="../../../../nn/hid/CTR/Overview.html">CTR</a>::GyroscopeReader</CODE> Class</h1> 52<h2>Syntax</h2> 53 <div class="section"> 54 <pre class="definition">class GyroscopeReader : private <a href="../../../../nn/util/NonCopyable/Overview.html">nn::util::NonCopyable< GyroscopeReader ></a></pre> 55 </div> 56<h2>Description</h2> 57 <div class="section"> 58<p>Class for loading sampling data from the gyro sensor.</p><h3>Sampling Rate</h3><p> 59Samples the angular velocity of the gyro sensor an average of every 10 milliseconds. If you want to monitor the exact timing of sampling, you can use the <CODE><a href="../../../../nn/hid/CTR/Gyroscope/Overview.html">Gyroscope</a></CODE> class to know precisely when sampling occurs.<BR /></p><h3>Output Value Details</h3> 60This class stores sampling results in a <CODE><a href="../../../../nn/hid/CTR/GyroscopeStatus/Overview.html">GyroscopeStatus</a></CODE> structure. This structure contains not just the angular velocity, but also attitude information calculated from the angular velocity. Because attitude is calculated when the <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html">Read</a></CODE> or <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html">ReadLatest</a></CODE> function is called, one of these functions must be called regularly (ideally in every frame). Data stored in the internal buffer can become discontinuous, resulting in less accurate attitude information, if too much time elapses between calls to either of these functions. 61<h3>Conditions to Start Sampling</h3><p> 62The gyro sensor halts sampling and transitions to sleep in two cases: when the system itself is in Sleep Mode, and when there are no instances of the <CODE>GyroscopeReader</CODE> class anywhere in the application. To explicitly stop sampling you must destroy all instances.<BR /><BR />It takes up to approximately 160 milliseconds for the sensor to transition from sleep to the active state where sampling is possible. No sampling is done during this transition time, and calls to the <a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html"><CODE>Read</CODE></a> and <a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html"><CODE>ReadLatest</CODE></a> functions do not yield valid results. To be sure to obtain sampling results, Nintendo recommends using the <CODE><a href="../../../../nn/hid/CTR/HidBase/WaitSampling.html">nn::hid::CTR::HidBase::WaitSampling</a></CODE> function in the <CODE><a href="../../../../nn/hid/CTR/Gyroscope/Overview.html">Gyroscope</a></CODE> class to wait until sampling has been performed at least once. Starting from the second instance, this sampling wait time is the same as the wait until the next sample, which is a maximum of approximately 10 milliseconds.<BR /> 63 </p><h3>Creating/Destroying Instances and Power-Supply Control</h3><p> 64As mentioned, creating or destroying instances serves as a trigger to switch the gyro sensor between the sleeping and active states. Frequent switching places a load on the device and results in more wear and tear on the device and higher power consumption. Try as much as possible to use the same instance throughout intervals where you are using gyro sensor output values, and avoid frequently creating or destroying instances. Below is an example of <U>what you should avoid</U>. 65 </p><pre><code> 66 void GetGyroscopeValue(f32* x,f32* y,f32* z) 67 { 68 GyroscopeReader reader; // Instance created: device is activated 69 GyroscopeStatus status; 70 71 reader.ReadLatest( &status ); // Get value 72 *x = status.speed.x; 73 *y = status.speed.y; 74 *z = status.speed.z; 75 76 return; // "reader" destroyed: device put to sleep 77 } 78 79 void MainLoop() // Loop called once per frame 80 { 81 ... some sort of processing ..... 82 GetGyroscopeValue( &x, &y, &z ); // Value obtained once in every frame 83 84 ... some sort of processing ..... 85 } 86 </code></pre><p> 87In the bad example above, an instance of <CODE>GyroscopeReader</CODE> is created and destroyed on the stack in every frame. It is impossible to get appropriate values because the gyro sensor has not met the launch time to go from Sleep Mode to active mode. The design should be revised, for example, by creating the instance in the heap, so that the instance continues to exist during the period when the application needs to get the angular velocity. 88 </p><h3>Correction Processing</h3><p> 89This class includes the following correction processing for getting information more accurately.<table><tr><th>Acceleration Correction</th><td>Uses the accelerometer to improve the accuracy of CTR attitude calculations.</td></tr><tr><th>Zero-Point Drift Correction</th><td>The gyro sensor's zero point can drift due to environmental factors. This correction automatically detects zero-point drift and adjusts angular velocity values accordingly.</td></tr></table><br />All correction processes are enabled by default, but can be configured or disabled as necessary. For details, see the various function references. 90</p><h3>Output Value Processing Features</h3><p> 91This class includes the following features to process output values.<table><tr><th>Zero-Point Play Tolerance</th><td>When the sampling results are within any radius centered on the zero-point, that is output as the zero-point.<br />This is used when, for example, you don't want to reflect small movements in the output.</td></tr><tr><th>Axial Rotation</th><td>The sampling results are multiplied by any rotational matrix and then output.<br />You can get output that reflects placement of the gyro sensor at an angle.</td></tr></table><BR />All processing features are disabled by default. Configure and enable them as needed. For details, see the various function references. 92</p><h3>Axis Orientation</h3><p> 93The default gyro sensor axes are as follows.<table><tr><th>X+</th><td>A clockwise rotation about the direction indicated by the Left Button on the +Control Pad.</td></tr><tr><th>Y+</th><td>A clockwise rotation about the direction normal to and outward from the Touch Screen.</td></tr><tr><th>Z+</th><td>A clockwise rotation about the direction indicated by the Up Button on the +Control Pad.</td></tr></table></p><h3>Recalibration of Accelerometer from HOME Menu</h3><p> 94A future update to the HOME menu will add a feature enabling users to recalibrate the accelerometer whenever they like.<br /><br />As a result, correction in accordance with the user's environment may start while the user is transitioned from the application to the HOME Menu using the HOME Button.<br />After this operation, the values obtained by the <a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html"><CODE>Read</CODE></a> and <a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html"><CODE>ReadLatest</CODE></a> functions are the corrected values. In most cases, the corrected values accurately reflect the user's environment.<br /><br />The applications, however, need not take any special measures to deal with this. 95</p><h3>Miscellaneous Notes</h3><p> 96This class maintains an internal instance of <CODE><a href="../../../../nn/hid/CTR/AccelerometerReader/Overview.html">AccelerometerReader</a></CODE> for acceleration correction, so generating an instance of this class activates the accelerometer. 97 </p></div> 98 <a name="constant" id="constant"> 99<h2>Member Constants</h2> 100 <div class="section"> 101 <table class="members"> 102 <tr> 103 <td width="100"> 104<span class="static_style" title="static">S</span> 105 </td> 106 <th> 107<span class="argument"><a href="../../../../nn/hid/CTR/GyroscopeReader/MAX_READ_NUM.html">MAX_READ_NUM</a></span> 108 </th> 109<td width="100">const <a href="../../../../nn_types/s8.html">s8</a></td> 110<td>The maximum number of data samples that can be read.</td> 111 </tr> </table> 112 </div> 113 </a> <a name="function" id="function"> 114<h2>Member Functions</h2> 115 <div class="section"> 116 <table class="members"> 117 <tr> 118<th class="category" colspan="3">Constructors and Destructors</th> 119 </tr> 120 <tr> 121 <td width="100"> </td> 122 <th> 123<a href="../../../../nn/hid/CTR/GyroscopeReader/GyroscopeReader.html"><CODE>GyroscopeReader</CODE></a> 124 </th> 125<td>Constructor.</td> 126 </tr> 127 <tr> 128 <td width="100"> </td> 129 <th> 130<a href="../../../../nn/hid/CTR/GyroscopeReader/~GyroscopeReader.html"><CODE>~GyroscopeReader</CODE></a> 131 </th> 132<td>Destructor.</td> 133 </tr> 134 <tr> 135<th class="category" colspan="3">Reading Sampling Data</th> 136 </tr> 137 <tr> 138 <td width="100"> </td> 139 <th> 140<a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html"><CODE>Read</CODE></a> 141 </th> 142<td>Loads sampling data from the gyro sensor, starting with the most recent data. Does not load any data that has been previously loaded.</td> 143 </tr> 144 <tr> 145 <td width="100"> </td> 146 <th> 147<a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html"><CODE>ReadLatest</CODE></a> 148 </th> 149<td>Loads the most recent sampling data from the gyro sensor. Unlike the <a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html"><CODE>Read</CODE></a> function, this function can load the same sampling data more than once.</td> 150 </tr> 151 <tr> 152<th class="category" colspan="3">Reset</th> 153 </tr> 154 <tr> 155 <td width="100"> </td> 156 <th> 157<a href="../../../../nn/hid/CTR/GyroscopeReader/Reset.html"><CODE>Reset</CODE></a> 158 </th> 159<td>Initializes internal settings.</td> 160 </tr> 161 <tr> 162<th class="category" colspan="3">Output Value Settings</th> 163 </tr> 164 <tr> 165 <td width="100"> </td> 166 <th> 167<a href="../../../../nn/hid/CTR/GyroscopeReader/SetAngle.html"><CODE>SetAngle</CODE></a> 168 </th> 169<td>Resets to an arbitrary value the <code>angle</code> member of the <CODE><a href="../../../../nn/hid/CTR/GyroscopeStatus/Overview.html">GyroscopeStatus</a></CODE> Structure (obtained by the <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html">Read</a></CODE> and <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html">ReadLatest</a></CODE> functions).</td> 170 </tr> 171 <tr> 172 <td width="100"> </td> 173 <th> 174<a href="../../../../nn/hid/CTR/GyroscopeReader/SetDirection.html"><CODE>SetDirection</CODE></a> 175 </th> 176<td>Resets to an arbitrary value the <code>direction</code> member of the <CODE><a href="../../../../nn/hid/CTR/GyroscopeStatus/Overview.html">GyroscopeStatus</a></CODE> structure (obtained by the <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html">Read</a></CODE> and <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html">ReadLatest</a></CODE> functions).</td> 177 </tr> 178 <tr> 179 <td width="100"> </td> 180 <th> 181<a href="../../../../nn/hid/CTR/GyroscopeReader/SetAngleMagnification.html"><CODE>SetAngleMagnification</CODE></a> 182 </th> 183<td>Sets individual scaling factors to apply for each axis when calculating angular velocity.</td> 184 </tr> 185 <tr> 186 <td width="100"> </td> 187 <th> 188<a href="../../../../nn/hid/CTR/GyroscopeReader/SetDirectionMagnification.html"><CODE>SetDirectionMagnification</CODE></a> 189 </th> 190<td>Sets the scaling factor to apply to the angular velocity used when calculating the <CODE>direction</CODE> member of the <CODE><a href="../../../../nn/hid/CTR/GyroscopeStatus/Overview.html">GyroscopeStatus</a></CODE> structure, which is obtained by the <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/Read.html">Read</a></CODE> and <CODE><a href="../../../../nn/hid/CTR/GyroscopeReader/ReadLatest.html">ReadLatest</a></CODE> functions.</td> 191 </tr> 192 <tr> 193<th class="category" colspan="3">Zero-Point Play Tolerance</th> 194 </tr> 195 <tr> 196 <td width="100"> </td> 197 <th> 198<a href="../../../../nn/hid/CTR/GyroscopeReader/EnableZeroPlay.html"><CODE>EnableZeroPlay</CODE></a> 199 </th> 200<td>Enables zero-point play tolerance.</td> 201 </tr> 202 <tr> 203 <td width="100"> </td> 204 <th> 205<a href="../../../../nn/hid/CTR/GyroscopeReader/DisableZeroPlay.html"><CODE>DisableZeroPlay</CODE></a> 206 </th> 207<td>Disables the zero-point play tolerance.</td> 208 </tr> 209 <tr> 210 <td width="100"> </td> 211 <th> 212<a href="../../../../nn/hid/CTR/GyroscopeReader/IsEnableZeroPlay.html"><CODE>IsEnableZeroPlay</CODE></a> 213 </th> 214<td>Checks whether zero-point play tolerance is enabled.</td> 215 </tr> 216 <tr> 217 <td width="100"> </td> 218 <th> 219<a href="../../../../nn/hid/CTR/GyroscopeReader/GetZeroPlayEffect.html"><CODE>GetZeroPlayEffect</CODE></a> 220 </th> 221<td>Gets the strength of correction applied by the zero-point play tolerance.</td> 222 </tr> 223 <tr> 224 <td width="100"> </td> 225 <th> 226<a href="../../../../nn/hid/CTR/GyroscopeReader/SetZeroPlayParam.html"><CODE>SetZeroPlayParam</CODE></a> 227 </th> 228<td>Sets the zero-point (at-rest) play tolerance.</td> 229 </tr> 230 <tr> 231 <td width="100"> </td> 232 <th> 233<a href="../../../../nn/hid/CTR/GyroscopeReader/GetZeroPlayParam.html"><CODE>GetZeroPlayParam</CODE></a> 234 </th> 235<td>Gets the zero-point play tolerance.</td> 236 </tr> 237 <tr> 238 <td width="100"> </td> 239 <th> 240<a href="../../../../nn/hid/CTR/GyroscopeReader/ResetZeroPlayParam.html"><CODE>ResetZeroPlayParam</CODE></a> 241 </th> 242<td>Initializes the zero-point play tolerance.</td> 243 </tr> 244 <tr> 245<th class="category" colspan="3">Zero-Point Drift Correction</th> 246 </tr> 247 <tr> 248 <td width="100"> </td> 249 <th> 250<a href="../../../../nn/hid/CTR/GyroscopeReader/EnableZeroDrift.html"><CODE>EnableZeroDrift</CODE></a> 251 </th> 252<td>Enables zero-point drift correction.</td> 253 </tr> 254 <tr> 255 <td width="100"> </td> 256 <th> 257<a href="../../../../nn/hid/CTR/GyroscopeReader/DisableZeroDrift.html"><CODE>DisableZeroDrift</CODE></a> 258 </th> 259<td>Disables zero-point drift correction.</td> 260 </tr> 261 <tr> 262 <td width="100"> </td> 263 <th> 264<a href="../../../../nn/hid/CTR/GyroscopeReader/IsEnableZeroDrift.html"><CODE>IsEnableZeroDrift</CODE></a> 265 </th> 266<td>Checks whether zero-point drift correction is enabled.</td> 267 </tr> 268 <tr> 269 <td width="100"> </td> 270 <th> 271<a href="../../../../nn/hid/CTR/GyroscopeReader/GetZeroDriftEffect.html"><CODE>GetZeroDriftEffect</CODE></a> 272 </th> 273<td>Gets the strength of zero-point drift correction.</td> 274 </tr> 275 <tr> 276 <td width="100"> </td> 277 <th> 278<a href="../../../../nn/hid/CTR/GyroscopeReader/ResetZeroDriftMode.html"><CODE>ResetZeroDriftMode</CODE></a> 279 </th> 280<td>Initializes the zero-point drift correction mode.</td> 281 </tr> 282 <tr> 283 <td width="100"> </td> 284 <th> 285<a href="../../../../nn/hid/CTR/GyroscopeReader/SetZeroDriftMode.html"><CODE>SetZeroDriftMode</CODE></a> 286 </th> 287<td>Sets the zero-point drift correction mode.</td> 288 </tr> 289 <tr> 290 <td width="100"> </td> 291 <th> 292<a href="../../../../nn/hid/CTR/GyroscopeReader/GetZeroDriftMode.html"><CODE>GetZeroDriftMode</CODE></a> 293 </th> 294<td>Gets the zero-point drift correction mode.</td> 295 </tr> 296 <tr> 297<th class="category" colspan="3">Acceleration Correction</th> 298 </tr> 299 <tr> 300 <td width="100"> </td> 301 <th> 302<a href="../../../../nn/hid/CTR/GyroscopeReader/EnableAccRevise.html"><CODE>EnableAccRevise</CODE></a> 303 </th> 304<td>Enables acceleration correction.</td> 305 </tr> 306 <tr> 307 <td width="100"> </td> 308 <th> 309<a href="../../../../nn/hid/CTR/GyroscopeReader/DisableAccRevise.html"><CODE>DisableAccRevise</CODE></a> 310 </th> 311<td>Disables acceleration correction.</td> 312 </tr> 313 <tr> 314 <td width="100"> </td> 315 <th> 316<a href="../../../../nn/hid/CTR/GyroscopeReader/IsEnableAccRevise.html"><CODE>IsEnableAccRevise</CODE></a> 317 </th> 318<td>Checks whether acceleration correction is enabled.</td> 319 </tr> 320 <tr> 321 <td width="100"> </td> 322 <th> 323<a href="../../../../nn/hid/CTR/GyroscopeReader/GetAccReviseEffect.html"><CODE>GetAccReviseEffect</CODE></a> 324 </th> 325<td>Gets the strength of acceleration correction.</td> 326 </tr> 327 <tr> 328 <td width="100"> </td> 329 <th> 330<a href="../../../../nn/hid/CTR/GyroscopeReader/SetAccReviseParam.html"><CODE>SetAccReviseParam</CODE></a> 331 </th> 332<td>Sets the weight and enabled range for acceleration correction.</td> 333 </tr> 334 <tr> 335 <td width="100"> </td> 336 <th> 337<a href="../../../../nn/hid/CTR/GyroscopeReader/GetAccReviseParam.html"><CODE>GetAccReviseParam</CODE></a> 338 </th> 339<td>Gets the weight and enabled range for acceleration correction.</td> 340 </tr> 341 <tr> 342 <td width="100"> </td> 343 <th> 344<a href="../../../../nn/hid/CTR/GyroscopeReader/ResetAccReviseParam.html"><CODE>ResetAccReviseParam</CODE></a> 345 </th> 346<td>Initializes the weight and enabled range for acceleration correction.</td> 347 </tr> 348 <tr> 349<th class="category" colspan="3">Axial Rotation</th> 350 </tr> 351 <tr> 352 <td width="100"> </td> 353 <th> 354<a href="../../../../nn/hid/CTR/GyroscopeReader/EnableAxisRotation.html"><CODE>EnableAxisRotation</CODE></a> 355 </th> 356<td>Enables axial rotation.</td> 357 </tr> 358 <tr> 359 <td width="100"> </td> 360 <th> 361<a href="../../../../nn/hid/CTR/GyroscopeReader/DisableAxisRotation.html"><CODE>DisableAxisRotation</CODE></a> 362 </th> 363<td>Disables axial rotation.</td> 364 </tr> 365 <tr> 366 <td width="100"> </td> 367 <th> 368<a href="../../../../nn/hid/CTR/GyroscopeReader/IsEnableAxisRotation.html"><CODE>IsEnableAxisRotation</CODE></a> 369 </th> 370<td>Checks whether axial rotation is enabled or disabled.</td> 371 </tr> 372 <tr> 373 <td width="100"> </td> 374 <th> 375<a href="../../../../nn/hid/CTR/GyroscopeReader/SetAxisRotationMatrix.html"><CODE>SetAxisRotationMatrix</CODE></a> 376 </th> 377<td>Sets the rotation matrix used for axial rotation.</td> 378 </tr> 379 <tr> 380 <td width="100"> </td> 381 <th> 382<a href="../../../../nn/hid/CTR/GyroscopeReader/GetAxisRotationMatrix.html"><CODE>GetAxisRotationMatrix</CODE></a> 383 </th> 384<td>Gets the rotation matrix used for axial rotation.</td> 385 </tr> 386 <tr> 387 <td width="100"> </td> 388 <th> 389<a href="../../../../nn/hid/CTR/GyroscopeReader/ResetAxisRotationMatrix.html"><CODE>ResetAxisRotationMatrix</CODE></a> 390 </th> 391<td>Initializes the rotation matrix used for axial rotation. When this function is called, the rotation matrix is set to a <a href="../../../../nn/math/MTX34/Overview.html"><CODE>nn::math::MTX34</CODE></a> identity matrix. This setting is equivalent to disabling axial rotation.</td> 392 </tr> </table> 393 </div> 394 </a> 395<h2>Class Hierarchy</h2> 396 <div class="section"> 397<p class="hierarchy"><CODE><a href="../../../../nn/util/NonCopyable/Overview.html">nn::util::NonCopyable</a></CODE><br /> <b><CODE>nn::hid::CTR::GyroscopeReader</CODE></b> 398 </p> 399 </div> 400<h2>Revision History</h2> 401 <div class="section"> 402 <dl class="history"> 403 <dt>2011/10/06</dt> 404<dd>Noted you cannot get values using the example of what <I>not</I> to do.<br /> 405 </dd> 406 <dt>2011/08/30</dt> 407<dd>Added text about creation and destruction of instances.<br /> 408 </dd> 409 <dt>2011/03/15</dt> 410<dd>Explained the possibility of accelerometer recalibration from the HOME Menu.<br /> 411 </dd> 412 <dt>2010/12/06</dt> 413<dd>Added explanation of conditions under which sampling stops.<br /> 414 </dd> 415 <dt>2010/10/20</dt> 416<dd>Initial version.<br /> 417 </dd> 418 </dl> 419 </div> 420 <hr><p>CONFIDENTIAL</p></body> 421</html> 422