src/joystick/darwin/SDL_sysjoystick.c
author Ryan C. Gordon <icculus@icculus.org>
Sun, 18 Mar 2007 22:39:24 +0000
changeset 2097 b0048df1701a
parent 1895 c121d94672cb
child 2109 51cbe188a49e
permissions -rw-r--r--
Merged r2992:2993 from branches/SDL-1.2: Mac OS X multi-axis joystick support.
     1 /*
     2 	SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2004 Sam Lantinga
     4 
     5 	This library is free software; you can redistribute it and/or
     6 	modify it under the terms of the GNU Library General Public
     7 	License as published by the Free Software Foundation; either
     8 	version 2 of the License, or (at your option) any later version.
     9 
    10 	This library is distributed in the hope that it will be useful,
    11 	but WITHOUT ANY WARRANTY; without even the implied warranty of
    12 	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13 	Library General Public License for more details.
    14 
    15 	You should have received a copy of the GNU Library General Public
    16 	License along with this library; if not, write to the Free
    17 	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    18 
    19 	Sam Lantinga
    20 	slouken@libsdl.org
    21 */
    22 #include "SDL_config.h"
    23 
    24 #ifdef SDL_JOYSTICK_IOKIT
    25 
    26 /* SDL joystick driver for Darwin / Mac OS X, based on the IOKit HID API */
    27 /* Written 2001 by Max Horn */
    28 
    29 #include <unistd.h>
    30 #include <ctype.h>
    31 #include <sysexits.h>
    32 #include <mach/mach.h>
    33 #include <mach/mach_error.h>
    34 #include <IOKit/IOKitLib.h>
    35 #include <IOKit/IOCFPlugIn.h>
    36 #ifdef MACOS_10_0_4
    37 #include <IOKit/hidsystem/IOHIDUsageTables.h>
    38 #else
    39 /* The header was moved here in Mac OS X 10.1 */
    40 #include <Kernel/IOKit/hidsystem/IOHIDUsageTables.h>
    41 #endif
    42 #include <IOKit/hid/IOHIDLib.h>
    43 #include <IOKit/hid/IOHIDKeys.h>
    44 #include <CoreFoundation/CoreFoundation.h>
    45 #include <Carbon/Carbon.h>      /* for NewPtrClear, DisposePtr */
    46 
    47 #include "SDL_joystick.h"
    48 #include "../SDL_sysjoystick.h"
    49 #include "../SDL_joystick_c.h"
    50 
    51 struct recElement
    52 {
    53     IOHIDElementCookie cookie;  /* unique value which identifies element, will NOT change */
    54     long min;                   /* reported min value possible */
    55     long max;                   /* reported max value possible */
    56 #if 0
    57     /* TODO: maybe should handle the following stuff somehow? */
    58 
    59     long scaledMin;             /* reported scaled min value possible */
    60     long scaledMax;             /* reported scaled max value possible */
    61     long size;                  /* size in bits of data return from element */
    62     Boolean relative;           /* are reports relative to last report (deltas) */
    63     Boolean wrapping;           /* does element wrap around (one value higher than max is min) */
    64     Boolean nonLinear;          /* are the values reported non-linear relative to element movement */
    65     Boolean preferredState;     /* does element have a preferred state (such as a button) */
    66     Boolean nullState;          /* does element have null state */
    67 #endif                          /* 0 */
    68 
    69     /* runtime variables used for auto-calibration */
    70     long minReport;             /* min returned value */
    71     long maxReport;             /* max returned value */
    72 
    73     struct recElement *pNext;   /* next element in list */
    74 };
    75 typedef struct recElement recElement;
    76 
    77 struct joystick_hwdata
    78 {
    79     IOHIDDeviceInterface **interface;   /* interface to device, NULL = no interface */
    80 
    81     char product[256];          /* name of product */
    82     long usage;                 /* usage page from IOUSBHID Parser.h which defines general usage */
    83     long usagePage;             /* usage within above page from IOUSBHID Parser.h which defines specific usage */
    84 
    85     long axes;                  /* number of axis (calculated, not reported by device) */
    86     long buttons;               /* number of buttons (calculated, not reported by device) */
    87     long hats;                  /* number of hat switches (calculated, not reported by device) */
    88     long elements;              /* number of total elements (shouldbe total of above) (calculated, not reported by device) */
    89 
    90     recElement *firstAxis;
    91     recElement *firstButton;
    92     recElement *firstHat;
    93 
    94     int removed;
    95     int uncentered;
    96 
    97     struct joystick_hwdata *pNext;      /* next device */
    98 };
    99 typedef struct joystick_hwdata recDevice;
   100 
   101 
   102 /* Linked list of all available devices */
   103 static recDevice *gpDeviceList = NULL;
   104 
   105 
   106 static void
   107 HIDReportErrorNum(char *strError, long numError)
   108 {
   109     SDL_SetError(strError);
   110 }
   111 
   112 static void HIDGetCollectionElements(CFMutableDictionaryRef deviceProperties,
   113                                      recDevice * pDevice);
   114 
   115 /* returns current value for element, polling element
   116  * will return 0 on error conditions which should be accounted for by application
   117  */
   118 
   119 static SInt32
   120 HIDGetElementValue(recDevice * pDevice, recElement * pElement)
   121 {
   122     IOReturn result = kIOReturnSuccess;
   123     IOHIDEventStruct hidEvent;
   124     hidEvent.value = 0;
   125 
   126     if (NULL != pDevice && NULL != pElement && NULL != pDevice->interface) {
   127         result =
   128             (*(pDevice->interface))->getElementValue(pDevice->interface,
   129                                                      pElement->cookie,
   130                                                      &hidEvent);
   131         if (kIOReturnSuccess == result) {
   132             /* record min and max for auto calibration */
   133             if (hidEvent.value < pElement->minReport)
   134                 pElement->minReport = hidEvent.value;
   135             if (hidEvent.value > pElement->maxReport)
   136                 pElement->maxReport = hidEvent.value;
   137         }
   138     }
   139 
   140     /* auto user scale */
   141     return hidEvent.value;
   142 }
   143 
   144 static SInt32
   145 HIDScaledCalibratedValue(recDevice * pDevice, recElement * pElement,
   146                          long min, long max)
   147 {
   148     float deviceScale = max - min;
   149     float readScale = pElement->maxReport - pElement->minReport;
   150     SInt32 value = HIDGetElementValue(pDevice, pElement);
   151     if (readScale == 0)
   152         return value;           /* no scaling at all */
   153     else
   154         return ((value - pElement->minReport) * deviceScale / readScale) +
   155             min;
   156 }
   157 
   158 
   159 static void
   160 HIDRemovalCallback(void *target, IOReturn result, void *refcon, void *sender)
   161 {
   162     recDevice *device = (recDevice *) refcon;
   163     device->removed = 1;
   164     device->uncentered = 1;
   165 }
   166 
   167 
   168 
   169 /* Create and open an interface to device, required prior to extracting values or building queues.
   170  * Note: appliction now owns the device and must close and release it prior to exiting
   171  */
   172 
   173 static IOReturn
   174 HIDCreateOpenDeviceInterface(io_object_t hidDevice, recDevice * pDevice)
   175 {
   176     IOReturn result = kIOReturnSuccess;
   177     HRESULT plugInResult = S_OK;
   178     SInt32 score = 0;
   179     IOCFPlugInInterface **ppPlugInInterface = NULL;
   180 
   181     if (NULL == pDevice->interface) {
   182         result =
   183             IOCreatePlugInInterfaceForService(hidDevice,
   184                                               kIOHIDDeviceUserClientTypeID,
   185                                               kIOCFPlugInInterfaceID,
   186                                               &ppPlugInInterface, &score);
   187         if (kIOReturnSuccess == result) {
   188             /* Call a method of the intermediate plug-in to create the device interface */
   189             plugInResult =
   190                 (*ppPlugInInterface)->QueryInterface(ppPlugInInterface,
   191                                                      CFUUIDGetUUIDBytes
   192                                                      (kIOHIDDeviceInterfaceID),
   193                                                      (void *) &(pDevice->
   194                                                                 interface));
   195             if (S_OK != plugInResult)
   196                 HIDReportErrorNum
   197                     ("CouldnŐt query HID class device interface from plugInInterface",
   198                      plugInResult);
   199             (*ppPlugInInterface)->Release(ppPlugInInterface);
   200         } else
   201             HIDReportErrorNum
   202                 ("Failed to create **plugInInterface via IOCreatePlugInInterfaceForService.",
   203                  result);
   204     }
   205     if (NULL != pDevice->interface) {
   206         result = (*(pDevice->interface))->open(pDevice->interface, 0);
   207         if (kIOReturnSuccess != result)
   208             HIDReportErrorNum
   209                 ("Failed to open pDevice->interface via open.", result);
   210         else
   211             (*(pDevice->interface))->setRemovalCallback(pDevice->interface,
   212                                                         HIDRemovalCallback,
   213                                                         pDevice, pDevice);
   214 
   215     }
   216     return result;
   217 }
   218 
   219 /* Closes and releases interface to device, should be done prior to exting application
   220  * Note: will have no affect if device or interface do not exist
   221  * application will "own" the device if interface is not closed
   222  * (device may have to be plug and re-plugged in different location to get it working again without a restart)
   223  */
   224 
   225 static IOReturn
   226 HIDCloseReleaseInterface(recDevice * pDevice)
   227 {
   228     IOReturn result = kIOReturnSuccess;
   229 
   230     if ((NULL != pDevice) && (NULL != pDevice->interface)) {
   231         /* close the interface */
   232         result = (*(pDevice->interface))->close(pDevice->interface);
   233         if (kIOReturnNotOpen == result) {
   234             /* do nothing as device was not opened, thus can't be closed */
   235         } else if (kIOReturnSuccess != result)
   236             HIDReportErrorNum("Failed to close IOHIDDeviceInterface.",
   237                               result);
   238         /* release the interface */
   239         result = (*(pDevice->interface))->Release(pDevice->interface);
   240         if (kIOReturnSuccess != result)
   241             HIDReportErrorNum("Failed to release IOHIDDeviceInterface.",
   242                               result);
   243         pDevice->interface = NULL;
   244     }
   245     return result;
   246 }
   247 
   248 /* extracts actual specific element information from each element CF dictionary entry */
   249 
   250 static void
   251 HIDGetElementInfo(CFTypeRef refElement, recElement * pElement)
   252 {
   253     long number;
   254     CFTypeRef refType;
   255 
   256     refType = CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementCookieKey));
   257     if (refType && CFNumberGetValue(refType, kCFNumberLongType, &number))
   258         pElement->cookie = (IOHIDElementCookie) number;
   259     refType = CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementMinKey));
   260     if (refType && CFNumberGetValue(refType, kCFNumberLongType, &number))
   261         pElement->min = number;
   262     pElement->maxReport = pElement->min;
   263     refType = CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementMaxKey));
   264     if (refType && CFNumberGetValue(refType, kCFNumberLongType, &number))
   265         pElement->max = number;
   266     pElement->minReport = pElement->max;
   267 /*
   268 	TODO: maybe should handle the following stuff somehow?
   269 
   270 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementScaledMinKey));
   271 	if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
   272 		pElement->scaledMin = number;
   273 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementScaledMaxKey));
   274 	if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
   275 		pElement->scaledMax = number;
   276 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementSizeKey));
   277 	if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
   278 		pElement->size = number;
   279 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsRelativeKey));
   280 	if (refType)
   281 		pElement->relative = CFBooleanGetValue (refType);
   282 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsWrappingKey));
   283 	if (refType)
   284 		pElement->wrapping = CFBooleanGetValue (refType);
   285 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsNonLinearKey));
   286 	if (refType)
   287 		pElement->nonLinear = CFBooleanGetValue (refType);
   288 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementHasPreferedStateKey));
   289 	if (refType)
   290 		pElement->preferredState = CFBooleanGetValue (refType);
   291 	refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementHasNullStateKey));
   292 	if (refType)
   293 		pElement->nullState = CFBooleanGetValue (refType);
   294 */
   295 }
   296 
   297 /* examines CF dictionary vlaue in device element hierarchy to determine if it is element of interest or a collection of more elements
   298  * if element of interest allocate storage, add to list and retrieve element specific info
   299  * if collection then pass on to deconstruction collection into additional individual elements
   300  */
   301 
   302 static void
   303 HIDAddElement(CFTypeRef refElement, recDevice * pDevice)
   304 {
   305     recElement *element = NULL;
   306     recElement **headElement = NULL;
   307     long elementType, usagePage, usage;
   308     CFTypeRef refElementType =
   309         CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementTypeKey));
   310     CFTypeRef refUsagePage =
   311         CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementUsagePageKey));
   312     CFTypeRef refUsage =
   313         CFDictionaryGetValue(refElement, CFSTR(kIOHIDElementUsageKey));
   314 
   315 
   316     if ((refElementType)
   317         &&
   318         (CFNumberGetValue(refElementType, kCFNumberLongType, &elementType))) {
   319         /* look at types of interest */
   320         if ((elementType == kIOHIDElementTypeInput_Misc)
   321             || (elementType == kIOHIDElementTypeInput_Button)
   322             || (elementType == kIOHIDElementTypeInput_Axis)) {
   323             if (refUsagePage
   324                 && CFNumberGetValue(refUsagePage, kCFNumberLongType,
   325                                     &usagePage) && refUsage
   326                 && CFNumberGetValue(refUsage, kCFNumberLongType, &usage)) {
   327                 switch (usagePage) {    /* only interested in kHIDPage_GenericDesktop and kHIDPage_Button */
   328                 case kHIDPage_GenericDesktop:
   329                     {
   330                         switch (usage) {        /* look at usage to determine function */
   331                         case kHIDUsage_GD_X:
   332                         case kHIDUsage_GD_Y:
   333                         case kHIDUsage_GD_Z:
   334                         case kHIDUsage_GD_Rx:
   335                         case kHIDUsage_GD_Ry:
   336                         case kHIDUsage_GD_Rz:
   337                         case kHIDUsage_GD_Slider:
   338                         case kHIDUsage_GD_Dial:
   339                         case kHIDUsage_GD_Wheel:
   340                             element = (recElement *)
   341                                 NewPtrClear(sizeof(recElement));
   342                             if (element) {
   343                                 pDevice->axes++;
   344                                 headElement = &(pDevice->firstAxis);
   345                             }
   346                             break;
   347                         case kHIDUsage_GD_Hatswitch:
   348                             element = (recElement *)
   349                                 NewPtrClear(sizeof(recElement));
   350                             if (element) {
   351                                 pDevice->hats++;
   352                                 headElement = &(pDevice->firstHat);
   353                             }
   354                             break;
   355                         }
   356                     }
   357                     break;
   358                 case kHIDPage_Button:
   359                     element = (recElement *)
   360                         NewPtrClear(sizeof(recElement));
   361                     if (element) {
   362                         pDevice->buttons++;
   363                         headElement = &(pDevice->firstButton);
   364                     }
   365                     break;
   366                 default:
   367                     break;
   368                 }
   369             }
   370         } else if (kIOHIDElementTypeCollection == elementType)
   371             HIDGetCollectionElements((CFMutableDictionaryRef) refElement,
   372                                      pDevice);
   373     }
   374 
   375     if (element && headElement) {       /* add to list */
   376         pDevice->elements++;
   377         if (NULL == *headElement)
   378             *headElement = element;
   379         else {
   380             recElement *elementPrevious, *elementCurrent;
   381             elementCurrent = *headElement;
   382             while (elementCurrent) {
   383                 elementPrevious = elementCurrent;
   384                 elementCurrent = elementPrevious->pNext;
   385             }
   386             elementPrevious->pNext = element;
   387         }
   388         element->pNext = NULL;
   389         HIDGetElementInfo(refElement, element);
   390     }
   391 }
   392 
   393 /* collects information from each array member in device element list (each array memeber = element) */
   394 
   395 static void
   396 HIDGetElementsCFArrayHandler(const void *value, void *parameter)
   397 {
   398     if (CFGetTypeID(value) == CFDictionaryGetTypeID())
   399         HIDAddElement((CFTypeRef) value, (recDevice *) parameter);
   400 }
   401 
   402 /* handles retrieval of element information from arrays of elements in device IO registry information */
   403 
   404 static void
   405 HIDGetElements(CFTypeRef refElementCurrent, recDevice * pDevice)
   406 {
   407     CFTypeID type = CFGetTypeID(refElementCurrent);
   408     if (type == CFArrayGetTypeID()) {   /* if element is an array */
   409         CFRange range = { 0, CFArrayGetCount(refElementCurrent) };
   410         /* CountElementsCFArrayHandler called for each array member */
   411         CFArrayApplyFunction(refElementCurrent, range,
   412                              HIDGetElementsCFArrayHandler, pDevice);
   413     }
   414 }
   415 
   416 /* handles extracting element information from element collection CF types
   417  * used from top level element decoding and hierarchy deconstruction to flatten device element list
   418  */
   419 
   420 static void
   421 HIDGetCollectionElements(CFMutableDictionaryRef deviceProperties,
   422                          recDevice * pDevice)
   423 {
   424     CFTypeRef refElementTop =
   425         CFDictionaryGetValue(deviceProperties, CFSTR(kIOHIDElementKey));
   426     if (refElementTop)
   427         HIDGetElements(refElementTop, pDevice);
   428 }
   429 
   430 /* use top level element usage page and usage to discern device usage page and usage setting appropriate vlaues in device record */
   431 
   432 static void
   433 HIDTopLevelElementHandler(const void *value, void *parameter)
   434 {
   435     CFTypeRef refCF = 0;
   436     if (CFGetTypeID(value) != CFDictionaryGetTypeID())
   437         return;
   438     refCF = CFDictionaryGetValue(value, CFSTR(kIOHIDElementUsagePageKey));
   439     if (!CFNumberGetValue
   440         (refCF, kCFNumberLongType, &((recDevice *) parameter)->usagePage))
   441         SDL_SetError("CFNumberGetValue error retrieving pDevice->usagePage.");
   442     refCF = CFDictionaryGetValue(value, CFSTR(kIOHIDElementUsageKey));
   443     if (!CFNumberGetValue
   444         (refCF, kCFNumberLongType, &((recDevice *) parameter)->usage))
   445         SDL_SetError("CFNumberGetValue error retrieving pDevice->usage.");
   446 }
   447 
   448 /* extracts device info from CF dictionary records in IO registry */
   449 
   450 static void
   451 HIDGetDeviceInfo(io_object_t hidDevice, CFMutableDictionaryRef hidProperties,
   452                  recDevice * pDevice)
   453 {
   454     CFMutableDictionaryRef usbProperties = 0;
   455     io_registry_entry_t parent1, parent2;
   456 
   457     /* Mac OS X currently is not mirroring all USB properties to HID page so need to look at USB device page also
   458      * get dictionary for usb properties: step up two levels and get CF dictionary for USB properties
   459      */
   460     if ((KERN_SUCCESS ==
   461          IORegistryEntryGetParentEntry(hidDevice, kIOServicePlane, &parent1))
   462         && (KERN_SUCCESS ==
   463             IORegistryEntryGetParentEntry(parent1, kIOServicePlane, &parent2))
   464         && (KERN_SUCCESS ==
   465             IORegistryEntryCreateCFProperties(parent2, &usbProperties,
   466                                               kCFAllocatorDefault,
   467                                               kNilOptions))) {
   468         if (usbProperties) {
   469             CFTypeRef refCF = 0;
   470             /* get device info
   471              * try hid dictionary first, if fail then go to usb dictionary
   472              */
   473 
   474 
   475             /* get product name */
   476             refCF =
   477                 CFDictionaryGetValue(hidProperties, CFSTR(kIOHIDProductKey));
   478             if (!refCF)
   479                 refCF =
   480                     CFDictionaryGetValue(usbProperties,
   481                                          CFSTR("USB Product Name"));
   482             if (refCF) {
   483                 if (!CFStringGetCString
   484                     (refCF, pDevice->product, 256,
   485                      CFStringGetSystemEncoding()))
   486                     SDL_SetError
   487                         ("CFStringGetCString error retrieving pDevice->product.");
   488             }
   489 
   490             /* get usage page and usage */
   491             refCF =
   492                 CFDictionaryGetValue(hidProperties,
   493                                      CFSTR(kIOHIDPrimaryUsagePageKey));
   494             if (refCF) {
   495                 if (!CFNumberGetValue
   496                     (refCF, kCFNumberLongType, &pDevice->usagePage))
   497                     SDL_SetError
   498                         ("CFNumberGetValue error retrieving pDevice->usagePage.");
   499                 refCF =
   500                     CFDictionaryGetValue(hidProperties,
   501                                          CFSTR(kIOHIDPrimaryUsageKey));
   502                 if (refCF)
   503                     if (!CFNumberGetValue
   504                         (refCF, kCFNumberLongType, &pDevice->usage))
   505                         SDL_SetError
   506                             ("CFNumberGetValue error retrieving pDevice->usage.");
   507             }
   508 
   509             if (NULL == refCF) {        /* get top level element HID usage page or usage */
   510                 /* use top level element instead */
   511                 CFTypeRef refCFTopElement = 0;
   512                 refCFTopElement =
   513                     CFDictionaryGetValue(hidProperties,
   514                                          CFSTR(kIOHIDElementKey));
   515                 {
   516                     /* refCFTopElement points to an array of element dictionaries */
   517                     CFRange range = { 0, CFArrayGetCount(refCFTopElement) };
   518                     CFArrayApplyFunction(refCFTopElement, range,
   519                                          HIDTopLevelElementHandler, pDevice);
   520                 }
   521             }
   522 
   523             CFRelease(usbProperties);
   524         } else
   525             SDL_SetError
   526                 ("IORegistryEntryCreateCFProperties failed to create usbProperties.");
   527 
   528         if (kIOReturnSuccess != IOObjectRelease(parent2))
   529             SDL_SetError("IOObjectRelease error with parent2.");
   530         if (kIOReturnSuccess != IOObjectRelease(parent1))
   531             SDL_SetError("IOObjectRelease error with parent1.");
   532     }
   533 }
   534 
   535 
   536 static recDevice *
   537 HIDBuildDevice(io_object_t hidDevice)
   538 {
   539     recDevice *pDevice = (recDevice *) NewPtrClear(sizeof(recDevice));
   540     if (pDevice) {
   541         /* get dictionary for HID properties */
   542         CFMutableDictionaryRef hidProperties = 0;
   543         kern_return_t result =
   544             IORegistryEntryCreateCFProperties(hidDevice, &hidProperties,
   545                                               kCFAllocatorDefault,
   546                                               kNilOptions);
   547         if ((result == KERN_SUCCESS) && hidProperties) {
   548             /* create device interface */
   549             result = HIDCreateOpenDeviceInterface(hidDevice, pDevice);
   550             if (kIOReturnSuccess == result) {
   551                 HIDGetDeviceInfo(hidDevice, hidProperties, pDevice);    /* hidDevice used to find parents in registry tree */
   552                 HIDGetCollectionElements(hidProperties, pDevice);
   553             } else {
   554                 DisposePtr((Ptr) pDevice);
   555                 pDevice = NULL;
   556             }
   557             CFRelease(hidProperties);
   558         } else {
   559             DisposePtr((Ptr) pDevice);
   560             pDevice = NULL;
   561         }
   562     }
   563     return pDevice;
   564 }
   565 
   566 /* disposes of the element list associated with a device and the memory associated with the list
   567  */
   568 
   569 static void
   570 HIDDisposeElementList(recElement ** elementList)
   571 {
   572     recElement *pElement = *elementList;
   573     while (pElement) {
   574         recElement *pElementNext = pElement->pNext;
   575         DisposePtr((Ptr) pElement);
   576         pElement = pElementNext;
   577     }
   578     *elementList = NULL;
   579 }
   580 
   581 /* disposes of a single device, closing and releaseing interface, freeing memory fro device and elements, setting device pointer to NULL
   582  * all your device no longer belong to us... (i.e., you do not 'own' the device anymore)
   583  */
   584 
   585 static recDevice *
   586 HIDDisposeDevice(recDevice ** ppDevice)
   587 {
   588     kern_return_t result = KERN_SUCCESS;
   589     recDevice *pDeviceNext = NULL;
   590     if (*ppDevice) {
   591         /* save next device prior to disposing of this device */
   592         pDeviceNext = (*ppDevice)->pNext;
   593 
   594         /* free element lists */
   595         HIDDisposeElementList(&(*ppDevice)->firstAxis);
   596         HIDDisposeElementList(&(*ppDevice)->firstButton);
   597         HIDDisposeElementList(&(*ppDevice)->firstHat);
   598 
   599         result = HIDCloseReleaseInterface(*ppDevice);   /* function sanity checks interface value (now application does not own device) */
   600         if (kIOReturnSuccess != result)
   601             HIDReportErrorNum
   602                 ("HIDCloseReleaseInterface failed when trying to dipose device.",
   603                  result);
   604         DisposePtr((Ptr) * ppDevice);
   605         *ppDevice = NULL;
   606     }
   607     return pDeviceNext;
   608 }
   609 
   610 
   611 /* Function to scan the system for joysticks.
   612  * Joystick 0 should be the system default joystick.
   613  * This function should return the number of available joysticks, or -1
   614  * on an unrecoverable fatal error.
   615  */
   616 int
   617 SDL_SYS_JoystickInit(void)
   618 {
   619     IOReturn result = kIOReturnSuccess;
   620     mach_port_t masterPort = 0;
   621     io_iterator_t hidObjectIterator = 0;
   622     CFMutableDictionaryRef hidMatchDictionary = NULL;
   623     recDevice *device, *lastDevice;
   624     io_object_t ioHIDDeviceObject = 0;
   625 
   626     SDL_numjoysticks = 0;
   627 
   628     if (gpDeviceList) {
   629         SDL_SetError("Joystick: Device list already inited.");
   630         return -1;
   631     }
   632 
   633     result = IOMasterPort(bootstrap_port, &masterPort);
   634     if (kIOReturnSuccess != result) {
   635         SDL_SetError("Joystick: IOMasterPort error with bootstrap_port.");
   636         return -1;
   637     }
   638 
   639     /* Set up a matching dictionary to search I/O Registry by class name for all HID class devices. */
   640     hidMatchDictionary = IOServiceMatching(kIOHIDDeviceKey);
   641     if (hidMatchDictionary) {
   642         /* Add key for device type (joystick, in this case) to refine the matching dictionary. */
   643 
   644         /* NOTE: we now perform this filtering later
   645            UInt32 usagePage = kHIDPage_GenericDesktop;
   646            UInt32 usage = kHIDUsage_GD_Joystick;
   647            CFNumberRef refUsage = NULL, refUsagePage = NULL;
   648 
   649            refUsage = CFNumberCreate (kCFAllocatorDefault, kCFNumberIntType, &usage);
   650            CFDictionarySetValue (hidMatchDictionary, CFSTR (kIOHIDPrimaryUsageKey), refUsage);
   651            refUsagePage = CFNumberCreate (kCFAllocatorDefault, kCFNumberIntType, &usagePage);
   652            CFDictionarySetValue (hidMatchDictionary, CFSTR (kIOHIDPrimaryUsagePageKey), refUsagePage);
   653          */
   654     } else {
   655         SDL_SetError
   656             ("Joystick: Failed to get HID CFMutableDictionaryRef via IOServiceMatching.");
   657         return -1;
   658     }
   659 
   660     /*/ Now search I/O Registry for matching devices. */
   661     result =
   662         IOServiceGetMatchingServices(masterPort, hidMatchDictionary,
   663                                      &hidObjectIterator);
   664     /* Check for errors */
   665     if (kIOReturnSuccess != result) {
   666         SDL_SetError("Joystick: Couldn't create a HID object iterator.");
   667         return -1;
   668     }
   669     if (!hidObjectIterator) {   /* there are no joysticks */
   670         gpDeviceList = NULL;
   671         SDL_numjoysticks = 0;
   672         return 0;
   673     }
   674     /* IOServiceGetMatchingServices consumes a reference to the dictionary, so we don't need to release the dictionary ref. */
   675 
   676     /* build flat linked list of devices from device iterator */
   677 
   678     gpDeviceList = lastDevice = NULL;
   679 
   680     while ((ioHIDDeviceObject = IOIteratorNext(hidObjectIterator))) {
   681         /* build a device record */
   682         device = HIDBuildDevice(ioHIDDeviceObject);
   683         if (!device)
   684             continue;
   685 
   686         /* dump device object, it is no longer needed */
   687         result = IOObjectRelease(ioHIDDeviceObject);
   688 /*		if (KERN_SUCCESS != result)
   689 			HIDReportErrorNum ("IOObjectRelease error with ioHIDDeviceObject.", result);
   690 */
   691 
   692         /* Filter device list to non-keyboard/mouse stuff */
   693         if ( (device->usagePage != kHIDPage_GenericDesktop) ||
   694              ((device->usage != kHIDUsage_GD_Joystick &&
   695                device->usage != kHIDUsage_GD_GamePad &&
   696                device->usage != kHIDUsage_GD_MultiAxisController)) ) {
   697 
   698             /* release memory for the device */
   699             HIDDisposeDevice(&device);
   700             DisposePtr((Ptr) device);
   701             continue;
   702         }
   703 
   704         /* Add device to the end of the list */
   705         if (lastDevice)
   706             lastDevice->pNext = device;
   707         else
   708             gpDeviceList = device;
   709         lastDevice = device;
   710     }
   711     result = IOObjectRelease(hidObjectIterator);        /* release the iterator */
   712 
   713     /* Count the total number of devices we found */
   714     device = gpDeviceList;
   715     while (device) {
   716         SDL_numjoysticks++;
   717         device = device->pNext;
   718     }
   719 
   720     return SDL_numjoysticks;
   721 }
   722 
   723 /* Function to get the device-dependent name of a joystick */
   724 const char *
   725 SDL_SYS_JoystickName(int index)
   726 {
   727     recDevice *device = gpDeviceList;
   728 
   729     for (; index > 0; index--)
   730         device = device->pNext;
   731 
   732     return device->product;
   733 }
   734 
   735 /* Function to open a joystick for use.
   736  * The joystick to open is specified by the index field of the joystick.
   737  * This should fill the nbuttons and naxes fields of the joystick structure.
   738  * It returns 0, or -1 if there is an error.
   739  */
   740 int
   741 SDL_SYS_JoystickOpen(SDL_Joystick * joystick)
   742 {
   743     recDevice *device = gpDeviceList;
   744     int index;
   745 
   746     for (index = joystick->index; index > 0; index--)
   747         device = device->pNext;
   748 
   749     joystick->hwdata = device;
   750     joystick->name = device->product;
   751 
   752     joystick->naxes = device->axes;
   753     joystick->nhats = device->hats;
   754     joystick->nballs = 0;
   755     joystick->nbuttons = device->buttons;
   756 
   757     return 0;
   758 }
   759 
   760 /* Function to update the state of a joystick - called as a device poll.
   761  * This function shouldn't update the joystick structure directly,
   762  * but instead should call SDL_PrivateJoystick*() to deliver events
   763  * and update joystick device state.
   764  */
   765 void
   766 SDL_SYS_JoystickUpdate(SDL_Joystick * joystick)
   767 {
   768     recDevice *device = joystick->hwdata;
   769     recElement *element;
   770     SInt32 value;
   771     int i;
   772 
   773     if (device->removed) {      /* device was unplugged; ignore it. */
   774         if (device->uncentered) {
   775             device->uncentered = 0;
   776 
   777             /* Tell the app that everything is centered/unpressed... */
   778             for (i = 0; i < device->axes; i++)
   779                 SDL_PrivateJoystickAxis(joystick, i, 0);
   780 
   781             for (i = 0; i < device->buttons; i++)
   782                 SDL_PrivateJoystickButton(joystick, i, 0);
   783 
   784             for (i = 0; i < device->hats; i++)
   785                 SDL_PrivateJoystickHat(joystick, i, SDL_HAT_CENTERED);
   786         }
   787 
   788         return;
   789     }
   790 
   791     element = device->firstAxis;
   792     i = 0;
   793     while (element) {
   794         value = HIDScaledCalibratedValue(device, element, -32768, 32767);
   795         if (value != joystick->axes[i])
   796             SDL_PrivateJoystickAxis(joystick, i, value);
   797         element = element->pNext;
   798         ++i;
   799     }
   800 
   801     element = device->firstButton;
   802     i = 0;
   803     while (element) {
   804         value = HIDGetElementValue(device, element);
   805         if (value > 1)          /* handle pressure-sensitive buttons */
   806             value = 1;
   807         if (value != joystick->buttons[i])
   808             SDL_PrivateJoystickButton(joystick, i, value);
   809         element = element->pNext;
   810         ++i;
   811     }
   812 
   813     element = device->firstHat;
   814     i = 0;
   815     while (element) {
   816         Uint8 pos = 0;
   817 
   818         value = HIDGetElementValue(device, element);
   819         if (element->max == 3)  /* 4 position hatswitch - scale up value */
   820             value *= 2;
   821         else if (element->max != 7)     /* Neither a 4 nor 8 positions - fall back to default position (centered) */
   822             value = -1;
   823         switch (value) {
   824         case 0:
   825             pos = SDL_HAT_UP;
   826             break;
   827         case 1:
   828             pos = SDL_HAT_RIGHTUP;
   829             break;
   830         case 2:
   831             pos = SDL_HAT_RIGHT;
   832             break;
   833         case 3:
   834             pos = SDL_HAT_RIGHTDOWN;
   835             break;
   836         case 4:
   837             pos = SDL_HAT_DOWN;
   838             break;
   839         case 5:
   840             pos = SDL_HAT_LEFTDOWN;
   841             break;
   842         case 6:
   843             pos = SDL_HAT_LEFT;
   844             break;
   845         case 7:
   846             pos = SDL_HAT_LEFTUP;
   847             break;
   848         default:
   849             /* Every other value is mapped to center. We do that because some
   850              * joysticks use 8 and some 15 for this value, and apparently
   851              * there are even more variants out there - so we try to be generous.
   852              */
   853             pos = SDL_HAT_CENTERED;
   854             break;
   855         }
   856         if (pos != joystick->hats[i])
   857             SDL_PrivateJoystickHat(joystick, i, pos);
   858         element = element->pNext;
   859         ++i;
   860     }
   861 
   862     return;
   863 }
   864 
   865 /* Function to close a joystick after use */
   866 void
   867 SDL_SYS_JoystickClose(SDL_Joystick * joystick)
   868 {
   869     /* Should we do anything here? */
   870     return;
   871 }
   872 
   873 /* Function to perform any system-specific joystick related cleanup */
   874 void
   875 SDL_SYS_JoystickQuit(void)
   876 {
   877     while (NULL != gpDeviceList)
   878         gpDeviceList = HIDDisposeDevice(&gpDeviceList);
   879 }
   880 
   881 #endif /* SDL_JOYSTICK_IOKIT */
   882 /* vi: set ts=4 sw=4 expandtab: */