src/joystick/darwin/SDL_sysjoystick.c
author Sam Lantinga <slouken@libsdl.org>
Sat, 10 Aug 2013 10:54:03 -0700
branchSDL-1.2
changeset 7625 952791dbe6ba
parent 6137 4720145f848b
child 8918 3c8124d60e8e
permissions -rw-r--r--
Fixed bug 2025 - Update 1.2 OSX Joystick code to fully support Saitek p2500 gamepad

Patrick Maloney

Saitek p2500 (Cyborg Rumble Force Pad) has a D-pad, two analog sticks, and numerous buttons. SDL 2.x on OSX detected everything except the right-side analog stick. The right-side stick is considered a 'simulation device' with the axes mapped to throttle and rudder.

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