Buffered Mouse Data

To retrieve buffered data from the mouse, you must first set the buffer size (see Device Properties). The default size of the buffer is 0, so this step is essential.

You must also declare an array of DIDEVICEOBJECTDATA structures. This array can have up to the same number of elements as the buffer size. You do not have to retrieve the entire contents of the buffer with a single call. You can have just one element in the array and retrieve events one at a time until the buffer is empty.

After acquiring the device, you can examine and flush events in the buffer at any time by using the IDirectInputDevice8::GetDeviceData method. (See Buffered and Immediate Data.) On return, each element in the DIDEVICEOBJECTDATA array represents a change in state for a single object on the mouse. For example, if the user presses button 0 and moves the mouse diagonally, the array passed to IDirectInputDevice8::GetDeviceData (if it has at least three elements, and pdwInOut is at least 3) will have three elements filled in-an element for button 0 being pressed, an element for the change in the x-axis, and an element for the change in the y-axis-and the value of pdwInOut will be set to 3.

You can determine which object an element in the array refers to by checking the dwOfs member of the DIDEVICEOBJECTDATA structure against the values returned by the following macros:

• DIMOFS_BUTTON0 to DIMOFS_BUTTON7
• DIMOFS_X
• DIMOFS_Y
• DIMOFS_Z

Each of these values is derived from the offset of the data for the object in a DIMOUSESTATE or DIMOUSESTATE2 structure. For example, DIMOFS_BUTTON0 is equivalent to the offset of rgbButtons[0] in the DIMOUSESTATE structure. DIMOFS_BUTTON4 to DIMOFS_BUTTON7 are supported only for DIMOUSESTATE2. With the macros you can use simple comparisons to determine which device object is associated with an item in the buffer. For example:

DIDEVICEOBJECTDATA  *lpdidod; 
int                 n; 
. 
. 
. 
/* MouseBuffer is an array of DIDEVICEOBJECTDATA structures 
   that has been set by a call to GetDeviceData. 
   n is incremented in a loop that examines all filled elements 
   in the array. */ 
lpdidod = &MouseBuffer[n]; 
if (( (int) lpdidod->dwOfs == DIMOFS_BUTTON0) 
      && (lpdidod->dwData & 0x80)) 
{ 
 ;  // Do something in response to left button press. 
} 

The data for the change of state of the device object is located in the dwData member of the DIDEVICEOBJECTDATA structure. For axes, the coordinate value is returned in this member. For button objects, only the low byte of dwData is significant. The high bit of this byte is set if the button was pressed, and it is clear if the button was released. In other words, the button was pressed if (dwData& 0x80) is nonzero.

If you are using Action Mapping, ignore the value in dwOfs and instead retrieve the application-defined data associated with the event from the uAppData member.

For more information about the other members of the DIDEVICEOBJECTDATA structure, see Time Stamps and Sequence Numbers.