di-diagnostics.cpp

Go to the documentation of this file.

/*
 * di-diagnostics.cpp
 *
 * Copyright (C) 2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Helper and diagnostic routines for the Microsoft DirectX DirectInput APIs
 */

// includes --------------------------------------------------------------------
#include "di-diagnostics.h"             // always include our own header first

#include <iostream>


namespace gamepad {


struct odf_type_entry_t {
        dword_t         type;   // type flag
        const char *    name;
};

#define ODFTYPE( token ) { DIDFT_ ##token , #token },

static const odf_type_entry_t s_odfTypes[] =
{
        ODFTYPE(ABSAXIS)
        ODFTYPE(ALIAS)
        ODFTYPE(AXIS)
        ODFTYPE(BUTTON)
        ODFTYPE(COLLECTION)
        ODFTYPE(FFACTUATOR)
        ODFTYPE(FFEFFECTTRIGGER)
        ODFTYPE(NOCOLLECTION)
        ODFTYPE(NODATA)
        ODFTYPE(OUTPUT)
        ODFTYPE(POV)
        ODFTYPE(PSHBUTTON)
        ODFTYPE(RELAXIS)
        ODFTYPE(TGLBUTTON)
        ODFTYPE(VENDORDEFINED)

        // must be last!
        { 0, NULL }
};


struct odf_flag_entry_t {
        dword_t         flag;   // flag value
        const char *    name;
};

#define ODFFLAG( token ) { DIDOI_ ##token , #token },

static const odf_flag_entry_t s_odfFlags[] =
{
        ODFFLAG(ASPECTACCEL)
        ODFFLAG(ASPECTFORCE)
        ODFFLAG(ASPECTPOSITION)
        ODFFLAG(ASPECTVELOCITY)

        // must be last!
        { 0, NULL }
};


struct dc_flag_entry_t {
        dword_t         flag;   // flag value
        const char *    name;
};

#define DCFLAG( token ) { DIDC_ ##token , #token },

static const dc_flag_entry_t s_dcFlags[] = {
        DCFLAG(ALIAS)
        DCFLAG(ATTACHED)
        DCFLAG(DEADBAND)
        DCFLAG(EMULATED)
        DCFLAG(FORCEFEEDBACK)
        DCFLAG(FFFADE)
        DCFLAG(FFATTACK)
        DCFLAG(HIDDEN)
        DCFLAG(PHANTOM)
        DCFLAG(POLLEDDATAFORMAT)
        DCFLAG(POLLEDDEVICE)
        DCFLAG(POSNEGCOEFFICIENTS)
        DCFLAG(POSNEGSATURATION)
        DCFLAG(SATURATION)
        DCFLAG(STARTDELAY)

        // must be last!
        { 0, NULL }
};



struct guid_entry_t {
        GUID            guid;
        const char *    name;
        const GUID *    pguid;
};

#define GUID_ENTRY(g) { GUID_ ## g , "GUID_" #g , &GUID_ ## g },

static const guid_entry_t s_guids[] = {
        GUID_ENTRY(XAxis)
        GUID_ENTRY(YAxis)
        GUID_ENTRY(ZAxis)
        GUID_ENTRY(RxAxis)
        GUID_ENTRY(RyAxis)
        GUID_ENTRY(RzAxis)
        GUID_ENTRY(Slider)
        GUID_ENTRY(Button)
        GUID_ENTRY(Key)
        GUID_ENTRY(POV)
        GUID_ENTRY(Unknown)

        // must be last
        { GUID_XAxis, NULL, NULL }
};


typedef std::vector<DIOBJECTDATAFORMAT> vec_objdf_t;


struct enum_objs_context_t {
        // constructor, manipulators
        enum_objs_context_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        objects.clear();
                        dc.clear();
                }

        // data fields
        vec_objdf_t             objects;        // vector of objects
        device_caps_t           dc;             // detected capabilities
};



////////////////////////////////////////////////////////////////////////////////
//
//      static helper methods
//
////////////////////////////////////////////////////////////////////////////////

static const GUID *
getGuidPointer
(
IN const GUID& rg
)
{
        for (const guid_entry_t * p = s_guids; p->pguid; ++p) {
                if (p->guid == rg) {
                        return p->pguid;
                }
        }

        // got here?  Unknown...
        std::cerr << "Unrecognized DirectInput object guid: " << rg << "\n";
        return NULL;
}



static const char *
getGuidName
(
IN const GUID * pg
)
{
        ASSERT(pg, "null");

        for (const guid_entry_t * p = s_guids; p->name; ++p) {
                if (p->guid == *pg) {
                        return p->name;
                }
        }

        // unknown!
        return "<unrecognized>";
}



static void
writeODFType
(
IO std::ostream& stream,
IN dword_t dwType
)
{
        for (const odf_type_entry_t * p = s_odfTypes; p->name; ++p) {
                if (dwType & p->type) {
                        stream << p->name << " ";
                }
        }
}



static void
writeODFFlags
(
IO std::ostream& stream,
IN dword_t dwFlags
)
{
        for (const odf_flag_entry_t * p = s_odfFlags; p->name; ++p) {
                if (dwFlags & p->flag) {
                        stream << p->name << " ";
                }
        }
}



static void
writeDCFlags
(
IO std::ostream& stream,
IN dword_t dwFlags
)
{
        for (const dc_flag_entry_t * p = s_dcFlags; p->name; ++p) {
                if (dwFlags & p->flag) {
                        stream << p->name << " ";
                }
        }
}



static BOOL CALLBACK
objectCallback
(
LPCDIDEVICEOBJECTINSTANCE lpddoi,
LPVOID pvRef
)
{
        ASSERT(lpddoi, "null");
        enum_objs_context_t * peoc = (enum_objs_context_t *) pvRef;
        ASSERT(peoc, "null");

        // do we care about this type?
        std::cerr << "Inspecting object: " << lpddoi->tszName << "\n";
        std::cerr << "  type: ";
        writeODFType(std::cerr, lpddoi->dwType);
        std::cerr << "\n";
        std::cerr << "  flags: ";
        writeODFFlags(std::cerr, lpddoi->dwFlags);
        std::cerr << "\n";
        std::cerr << "  guid: " << getGuidName(&lpddoi->guidType) << "\n";

        DIOBJECTDATAFORMAT odf;
        odf.dwType = lpddoi->dwType;
        odf.dwFlags = lpddoi->dwFlags;
        if (DIDFT_ABSAXIS & lpddoi->dwType) {
                DPRINTF("Absolute Axis!");
                peoc->dc.nAxes++;
        } else if (DIDFT_PSHBUTTON & lpddoi->dwType) {
                DPRINTF("Push button!");
                peoc->dc.nButtons++;
        } else if (DIDFT_POV & lpddoi->dwType) {
                DPRINTF("Dpad!");
                peoc->dc.nPOVs++;
        } else {
                DPRINTF("unknown type, skipping");
                return DIENUM_CONTINUE;
        }

        // update guid
        odf.pguid = getGuidPointer(lpddoi->guidType);

        // got here?  Add to collection
        peoc->objects.push_back(odf);

        // why did they declare it BOOL then define their own enums?
        return DIENUM_CONTINUE;
}



////////////////////////////////////////////////////////////////////////////////
//
//      public API
//
////////////////////////////////////////////////////////////////////////////////

#define DIE_VALUE(token) case token : DPRINTF("  ...%s", #token ); break;

void
checkDIError
(
IN HRESULT hr
)
{
        DPRINTF("Checking DirectInput result code 0x%08x = %ld...", hr, hr);
        switch (hr) {
        DIE_VALUE(DI_OK)
        DIE_VALUE(DIERR_ACQUIRED)
        DIE_VALUE(DIERR_DEVICENOTREG)
        DIE_VALUE(DIERR_INPUTLOST)
        DIE_VALUE(DIERR_INVALIDPARAM)
        DIE_VALUE(DIERR_NOINTERFACE)
        DIE_VALUE(DIERR_NOTINITIALIZED)
        DIE_VALUE(DIERR_OBJECTNOTFOUND)
        DIE_VALUE(DIERR_OTHERAPPHASPRIO)
        DIE_VALUE(DIERR_OUTOFMEMORY)
        DIE_VALUE(DIERR_UNSUPPORTED)
        default:
                DPRINTF("  ...not a recognized DirectInput result code!");
                DPRINTF("  Checking basic Windows HRESULT codes...");
                checkHresult(hr);
        }
}



void
writeDevInstance
(
IO std::ostream& stream,
IN const DIDEVICEINSTANCEA& di
)
{
        ASSERT_THROW(stream.good(), "bad stream?");

        stream << "DirectInput device instance structure:\n";
        int type = (di.dwDevType & 0xff);
        int subtype = ((di.dwDevType >> 8) & 0xff);
        stream << "  struct size: " << di.dwSize << " bytes\n";
        stream << "  type: " << type << ", subtype: " << subtype << "\n";
        stream << "  guidInstance: " << di.guidInstance << "\n";
        stream << "  guidProduct: " << di.guidProduct << "\n";
        stream << "  tszInstanceName: " << di.tszInstanceName << "\n";
        stream << "  tszFriendlyName: " << di.tszProductName << "\n";
        stream << "  guidFFDriver: " << di.guidFFDriver << "\n";
        stream << "  wUsagePage: " << di.wUsagePage << "\n";
        stream << "  wUsage: " << di.wUsage << "\n";
}



void
writeDevCaps
(
IO std::ostream& stream,
IN const DIDEVCAPS& dc
)
{
        ASSERT_THROW(stream.good(), "bad stream?");

        stream << "DirectInput device capabilities structure:\n";
        stream << "  size: " << dc.dwSize << " bytes\n";
        stream << "  flags: ";
        writeDCFlags(stream, dc.dwFlags);
        stream << "\n";
        int type = (int) (dc.dwDevType & 0xff);
        int subType = (int) ((dc.dwDevType >> 8) & 0xff);
        stream << "  type: " << type << "  subtype: " << subType << "\n";
        stream << "  axes: " << dc.dwAxes << "\n";
        stream << "  buttons: " << dc.dwButtons << "\n";
        stream << "  POVs: " << dc.dwPOVs << "\n";
        stream << "  sample period: " << dc.dwFFSamplePeriod << " ms\n";
        stream << "  min res: " << dc.dwFFMinTimeResolution << " ms\n";
        stream << "  firmware: " << dc.dwFirmwareRevision << "\n";
        stream << "  hardware: " << dc.dwHardwareRevision << "\n";
        stream << "  ff driver: " << dc.dwFFDriverVersion << "\n";
}



void
writeObjectDataFormat
(
IO std::ostream& stream,
IN const DIOBJECTDATAFORMAT& odf
)
{
        ASSERT_THROW(stream.good(), "bad stream?");

        stream << "  DirectInput object data format structure:\n";
        stream << "    guid: ";
        if (odf.pguid) {
                stream << getGuidName(odf.pguid) << "\n";
        } else {
                stream << "(null guid)\n";
        }
        stream << "    dwOfs: " << odf.dwOfs << " byte offset\n";
        stream << "    dwType: ";
        writeODFType(stream, odf.dwType);
        stream << "\n";
        stream << "    dwFlags: ";
        writeODFFlags(stream, odf.dwFlags);
        stream << "\n";
}



void
writeDataFormat
(
IO std::ostream& stream,
IN const DIDATAFORMAT& df
)
{
        ASSERT_THROW(stream.good(), "bad stream?");

        stream << "DirectInput data format structure:\n";
        stream << "  dwSize: " << df.dwSize << " bytes\n";
        stream << "  dwObjSize: " << df.dwObjSize << " bytes\n";
        stream << "  dwFlags: ";
        if (DIDF_ABSAXIS == df.dwFlags) {
                stream << "Absolute axes (ABSAXIS)\n";
        } else if (DIDF_RELAXIS == df.dwFlags) {
                stream << "Relative axes (RELAXIS)\n";
        } else {
                stream << "Unknown flags (" << df.dwFlags << ")\n";
        }
        stream << "  dwDataSize: " << df.dwDataSize << " bytes\n";
        stream << "  dwNumObjs: " << df.dwNumObjs << "\n";
        int nObjs = (int) df.dwNumObjs;
        for (int i = 0; i < nObjs; ++i) {
                writeObjectDataFormat(stream, df.rgodf[i]);
        }
}



void
writeStateDebug
(
IO std::ostream& stream,
IN const DIDATAFORMAT& df,
IN const byte_t * buffer
)
{
        ASSERT_THROW(stream.good(), "bad stream");
        ASSERT(df.dwSize > 0, "bad size");
        ASSERT(df.dwDataSize > 0, "bad data size");
        ASSERT(buffer, "null");

        int nObjs = (int) df.dwNumObjs;
        DPRINTF("Reading gamepad device state, contains %d objects...", nObjs);
        for (int i = 0; i < nObjs; ++i) {
                const DIOBJECTDATAFORMAT& rodf = df.rgodf[i];
                stream << "  Object " << i << ": ";
                stream << "guid=";
                if (rodf.pguid) {
                        stream << *rodf.pguid;
                } else {
                        stream << "(null)";
                }
                int offset = rodf.dwOfs;
                stream << " offset=" << offset;
                stream << " type=(";
                writeODFType(stream, rodf.dwType);
                stream << ") flags=(";
                writeODFFlags(stream, rodf.dwFlags);
                stream << ") value=";

                // we assume that only buttons are 1-byte values, and that all
                //      buttons have the BUTTON flag set.  And we furthermore
                //      assume that everything else is a int32 value.
                // Ideally MSDN would mention this information...
                if (DIDFT_BUTTON & rodf.dwType) {
                        byte_t b = buffer[offset];
                        stream << (int) b;
                } else {
                        const int32_t *pl = (const int32_t *) (buffer + offset);
                        int32_t val = *pl;
                        stream << val;
                }
                stream << "\n";
        }
}



void
writeState
(
IO std::ostream& stream,
IN const DIDATAFORMAT& df,
IN const byte_t * buffer
)
{
        ASSERT_THROW(stream.good(), "bad stream");
        ASSERT(df.dwSize > 0, "bad size");
        ASSERT(df.dwDataSize > 0, "bad data size");
        ASSERT(buffer, "null");

        int nObjs = (int) df.dwNumObjs;
        DPRINTF("Reading gamepad device state, contains %d objects...", nObjs);
        for (int i = 0; i < nObjs; ++i) {
                const DIOBJECTDATAFORMAT& rodf = df.rgodf[i];
                int offset = rodf.dwOfs;
                if (DIDFT_BUTTON & rodf.dwType) {
                        byte_t b = buffer[offset];
                        stream << (int) b;
                } else {
                        const int32_t *pl = (const int32_t *) (buffer + offset);
                        int32_t val = *pl;
                        stream << val;
                }
                stream << " ";
        }
        stream << "\n";
}



void
device_caps_t::dump
(
IN const char * title
)
const
throw()
{
        ASSERT(title, "NULL");
        DPRINTF("%s: %d axes, %d POVs, %d buttons",
            title, nAxes, nPOVs, nButtons);
}



byte_t *
getDataFormatForDevice
(
IN IDirectInputDevice8 * device,
OUT device_caps_t& dc
)
{
        ASSERT(device, "null");
        DPRINTF("Constructing data format for device");

        // first we construct our own dynamic array of objects
        // next, pack into a data structure that DirectInput understands

        // enumerate all objects on the device (gamepad)
        enum_objs_context_t eoc;
        device->EnumObjects(objectCallback, &eoc, DIDFT_ALL);
        DPRINTF("Found %u objects", eoc.objects.size());
 
        // construct output array
        int nObjs = eoc.objects.size();
        int nBytes = sizeof(DIDATAFORMAT) + nObjs * sizeof(DIOBJECTDATAFORMAT) + 2 * sizeof(LPVOID);
        byte_t * pb = new byte_t[nBytes];
        ASSERT(pb, "out of memory");

        // initialize
        DIDATAFORMAT * pdidf = (DIDATAFORMAT *) pb;
        pdidf->dwSize = sizeof(DIDATAFORMAT);
        pdidf->dwObjSize = sizeof(DIOBJECTDATAFORMAT);
        pdidf->dwNumObjs = nObjs;
        pdidf->dwDataSize = nObjs * sizeof(dword_t);
        pdidf->dwFlags = DIDF_ABSAXIS;

        // weird pointer math: we point to the location in the structure
        //      immediately after the pointer itself
        long * pl = (long *) &pdidf->rgodf;     // location of pointer
        DPRINTF("pl = %p", pl);
        ++pl;   // increment just past pointer
        pdidf->rgodf = (DIOBJECTDATAFORMAT *) pl;

        // set all of the individual objects
        DPRINTF("Setting %d objects...", nObjs);
        DIOBJECTDATAFORMAT * p = pdidf->rgodf;
        dword_t offset = 0;

        // first pass: axes
        for (int i = 0; i < nObjs; ++i) {
                const DIOBJECTDATAFORMAT& obj = eoc.objects[i];
                if (!(DIDFT_AXIS & obj.dwType))
                        continue;       // skip this one
                *p = obj;       // copy over to output array
                p->dwOfs = offset;
                offset += sizeof(dword_t);
                ++p;            // next 
        }

        // second pass: POVs
        for (int i = 0; i < nObjs; ++i) {
                const DIOBJECTDATAFORMAT& obj = eoc.objects[i];
                if (!(DIDFT_POV & obj.dwType))
                        continue;       // skip this one
                *p = obj;       // copy over to output array
                p->dwOfs = offset;
                offset += sizeof(dword_t);
                ++p;            // next 
        }

        // third pass: buttons
        for (int i = 0; i < nObjs; ++i) {
                const DIOBJECTDATAFORMAT& obj = eoc.objects[i];
                if (!(DIDFT_BUTTON & obj.dwType))
                        continue;       // skip this one
                *p = obj;       // copy over to output array
                p->dwOfs = offset;
                offset += sizeof(dword_t);
                ++p;            // next 
        }

        // verify we exactly filled our data size
        offset = (p - pdidf->rgodf);
        ASSERT(offset == pdidf->dwNumObjs,
            "Mismatch in offset: %d", offset);

        // all done!  Return to caller...
        dc = eoc.dc;
        dc.dataBytes = pdidf->dwDataSize;

        return pb;
}




int32_t
getPOVValue
(
IN const byte_t * data,
IN const device_caps_t& dc,
IN int povIndex
)
{
        ASSERT(data, "null");
        ASSERT(povIndex >= 0 && povIndex < dc.nPOVs,
            "Bad pov index: %d", povIndex);

        // get offset in dwords
        int offset = dc.nAxes + povIndex;

        // convert to byte offset, and increment data pointer
        offset *= sizeof(dword_t);
        data += offset;

        // return the int32 pointed to
        return *((int32_t *) data);
}



dword_t
getButtonValue
(
IN const byte_t * data,
IN const device_caps_t& dc,
IN int buttonIndex
)
{
        ASSERT(data, "null");
        ASSERT(buttonIndex >= 0 && buttonIndex < dc.nButtons,
            "Invalid button index: %d", buttonIndex);

        // get offset in number of DWORDs
        int offset = dc.nAxes + dc.nPOVs + buttonIndex;

        // convert to byte offset and increment the data pointer
        offset *= sizeof(dword_t);
        data += offset;

        // return the dword at that byte offset
        return *((dword_t *) data);
}



int32_t
getAxisValue
(
IN const byte_t * data,
IN const device_caps_t& dc,
IN int axisIndex
)
{
        ASSERT(data, "null");
        ASSERT(axisIndex >= 0 && axisIndex < dc.nAxes,
            "Bad axis index: %d", axisIndex);

        // get offset in DWORDs, convert to bytes
        int offset = axisIndex;
        offset *= sizeof(dword_t);

        // return value
        return *((int32_t *) (data + offset));
}



};      // gamepad namespace