PATH
SetHardwareCursor is a required routine for drivers that support hardware cursors. QuickDraw uses the SetHardwareCursor control call to set up the hardware cursor and determine whether the hardware can support it. The driver must determine whether it can support the given cursor and, if so, program the hardware cursor frame buffer (or equivalent), set up the CLUT, and return noErr. If the driver cannot support the cursor it must return controlErr. The driver must remember whether this call was successful for subsequent GetHardwareCursorDrawState or DrawHardwareCursor calls, but should not change the cursor's x or y coordinates or its visible state.
OSErr = Control (theDeviceRefNum, cscSetHardwareCursor,
&theVDSetHardwareCursorRec);
The driver should call the VSL routine VSLPrepareCursorForHardwareCursor with csCursorRef and the appropriate hardware cursor descriptor. This routine will do all the necessary conversion for the cursor passed in csCursorRef to match the hardware described in the hardware cursor descriptor. If the cursor passed in csCursorRef is compatible with the hardware cursor descriptor, the VSL call will return true ; otherwise, it will return false. It will also pass back a cursor image at the appropriate bit depth and pixel format for the hardware and a CTabPtr color table that specifies the colors for the cursor.
The driver should be able to copy the cursor image passed back from VSLPrepareCursorForHardwareCursor directly into its hardware cursor frame buffer (or equivalent) and program its CLUT, using the color table in a fashion similar to the SetEntries control call. As in the SetEntries control call, the driver must apply any gamma correction to the color table.
If a driver's hardware can support multiple hardware cursor formats, the driver can make multiple calls to VSLPrepareCursorForHardwareCursor with different hardware cursor descriptors until the call succeeds or all hardware cursor formats are exhausted.
If the driver must access the cursor data structure passed in csCursorRef, it can typecast it to a CursorImageRec defined in Quickdraw.h. However, the format of the cursor passed in with csCursorRef is subject to change in future releases of Mac OS; it is recommended that VSLPrepareCursorForHardwareCursor be used because it will be kept up to date with the format of csCursorRef.