VPAD Library Overview

Introduction

The VPAD library is a high-level abstraction for the Display Remote Control (DRC). This library interprets the raw sensor data into meaningful events for applications.

Process Flow

Getting Controller Information

To load the DRC information into the VPADStatus structure, use the VPADRead function. You can adjust how the controller reports certain data by calling the following functions beforehand:

The VPAD Library Specifications

VPADRead Function

The VPADRead function returns the number of sets of sampling data, or zero if there are none, and also returns the error code in the variable pointer passed as an argument. The error codes are as follows:

Error Code Description
VPAD_READ_ERR_NONE There is sampling data.
VPAD_READ_ERR_NO_DATA There is no sampling data.
VPAD_READ_ERR_NO_CONTROLLER The DRC is not connected.
VPAD_READ_ERR_SETUP VPADBASE library initialization is not complete.
VPAD_READ_ERR_LOCKED Duplicate calls caused failure to obtain permission to process.
VPAD_READ_ERR_INIT The VPADInit function has not been called.

Even when the VPADRead function returns zero, the contents of the sampling buffer passed to it as an argument may have changed. The only time that you can be certain that the contents of the sampling buffer have not changed is when VPAD_READ_ERR_NO_DATA is returned.

Multiple Calls to the VPADRead Functions

When VPADRead is called, the ring buffer inside the VPAD library is flushed. For this reason, if data is used by multiple threads, we recommend that you use a single thread and share the loaded data, rather than calling functions from multiple threads.

When the functions are called multiple times, they return zero when they fail to gain processing rights and the VPADRead function also returns the error code VPAD_READ_ERR_LOCKED.

Clamp Processing for the Stick

Stick clamp processing is implemented as circular clamping and cross-shape clamping. Circular clamping is used by default. Select clamp processing by using the VPADEnableStickCrossClamp and VPADDisableStickCrossClamp functions.

Processing +Control Pad Restrictions

Prohibition processing for the +Control Pad of the DRC is performed internally by the VPADBASE library. If the +Control Pad physically breaks and its input is in a state that is normally impossible, such as simultaneous presses of Left and Right, the library processes it as valid input of Left. Similarly, if Up and Down are simultaneously pressed, the library assumes the valid input to be Up.

Regarding Data Loss

The VPADRead function is designed with the assumption that they will be called once every game frame. However, if the interval between calls to these functions grows too long due to a processing slowdown or some other reason, the VPAD library's internal ring buffer might go full circle, and data could be lost.

Gyroscope

Overview

The sensors used in the DRC are rate sensors (gyroscopes). These rate sensors can get the angular velocity around the axes for pitch, yaw, and roll. The values for each axis are stored in the VPADStatus structure and obtained with the VPADRead function. The VPADStatus structure has the members gyro, angle, and dir. The first two are defined as type Vec. The Vec type direction components are as follows: x is the pitch, y is the yaw, and z is the roll. The gyro member represents the angular velocity in each direction and stores a value where 1.0 corresponds to 360 dps (degrees per second). The angle member represents the angle in each direction and stores a value where 1.0 corresponds to 360 degrees. The dir member represents the 3D attitude expressed as a 3x3 matrix.

Correction Processing

The VPAD library can perform the following corrections on DRC data.

Excluding zero-point drift correction, these correction processes can each be freely enabled or disabled. (Zero-point drift correction is always enabled.) Parameters can be used to adjust the degree of drift correction.

Zero-Point Play Tolerance

If this feature is enabled, the system does not respond to small movements. This feature is effective in situations where, for example, you want to capture only large movements in a particular direction. Specifically, there is no response to motion smaller than radius, specified by the VPADSetGyroZeroPlayParam function. The closer the current angular velocity is to the specified radius, the closer to zero the return value of the VPADIsEnableGyroZeroPlay function becomes.

Zero-Point Drift Correction

The zero point may drift due to effects such as temperature while the DRC is in use. This correction process works by first determining whether the DRC is stationary. This is performed by checking whether the DRC continues to return the same value for some interval of time. If the device is deemed to be stationary, the zero point is corrected to reflect the value. Also, three types of determination criteria have been prepared. Any one of these may be applied. The zero point is constantly corrected based on how well certain information, such as current acceleration and past angular acceleration being buffered internally, fits in the specified determination criteria. You can get information regarding how well data fits from the return value of the VPADIsEnableGyroZeroDrift function. The closer the value is to 1, the better the fit. You can also assume that the closer the value is to 1, the more stable the motion will be.

NOTE:
Because this type of processing is performed, this correction may also be performed unintentionally during constant, uniform motion. Be sure to consider this issue in scenes that request precise movements from the player. In such scenes, this issue can be addressed either by making stricter determination criteria or by setting up a play tolerance around the zero point.

Attitude Correction for the Base Attitude

By configuring a certain attitude as the base attitude, even vigorous swinging that cannot be handled by other correction processing stops causing the attitude to shift far from the base attitude.

Attitude Correction Using Acceleration

When this compensation is enabled, correction is applied using an acceleration value in cases where the acceleration obtained from the accelerometer fits inside the range given by the force of gravity plus revise_range, specified by the VPADSetGyroAccReviseParam function.

Temperature Drift and Integration Error

You can expect some degree of improvement in temperature drift when using the zero-point drift correction process. In addition, you should be able to mitigate drift to a certain degree by correcting acceleration before the error becomes too large, and by setting the base model beforehand for scenes in which motions are so small that these corrections are not triggered.

Calibration Value Errors

As stated in the specifications for DRC rate sensors, the scale value for the written calibration values can vary by as much as ±8% due to the effects of humidity, air temperature, and device age. This error cannot be mitigated by the VPAD library. When designing for the DRC, therefore, do not attempt to require an exact degree of accuracy.

When the VPADSetGyroMagnification function calculates angular speed, you can set a different scaling factor for each direction of motion. Because you can use this function to evaluate the effect that these errors in attitude and angle will actually have on calculations, use it when verifying that your game can be played within the range of error.

Determining Whether the Wii Remote Is at Rest

For more information, see the "Determining Whether the Wii Remote Is at Rest" section in the KPAD Overview. The DRC's case is the same as that of the Wii Remote.

Two DRC Support

Limited Development Support Only

SDK 2.09 includes limited support for two DRCs for development purposes only. For information about how to use two DRCs, refer to Two_DRC_VPAD sample.

Integration with HOME Menu and other system functionality is not supported.

DRC2 Not Present

The chan argument specifies the target controller number (DRC device) in VPAD library API. If (1) is specified for chan and DRC2 is not present, VPAD_READ_ERR_NO_CONTROLLER is returned in the VPADStatus.

See Also

DRC Controller Library (VPAD) API Function List
DRC High-Level Library (VPAD) Sample Demos

Revision History

2014/01/21 Terminology change to HOME Menu.
2013/05/08 Automated cleanup pass.
2012/07/25 Cleanup Pass
2011/04/30 Added the explanation of +Control Pad Restrictions.
2011/03/30 Initial version.


CONFIDENTIAL