PATH
Boolean VSLPrepareCursorForHardwareCursor
(void *cursorRef,
HardwareCursorDescriptorPtr hardwareDescriptor,
HardwareCursorInfoPtr hwCursorInfo);
If the cursorRef passed to the driver is capable of being rendered by the hardware cursor, VSLPrepareCursorForHardwareCursor returns true ; otherwise, it returns false. Cases where the routine returns false include a cursor needing more colors than the hardware can supply, a cursor that is too big, and a cursor requiring special pixel types that the hardware doesn't support, such as inverted pixels.
The driver uses the following structure to describe its hardware cursor:
enum {
kTransparentEncoding = 0,
kInvertingEncoding
};
enum {
kTransparentEncodingShift = (kTransparentEncoding << 1),
kTransparentEncodedPixel = (0x01 << kTransparentEncodingShift),
kInvertingEncodingShift = (kInvertingEncoding << 1),
kInvertingEncodedPixel = (0x01 << kInvertingEncodingShift),
};
enum {
kHardwareCursorDescriptorMajorVersion = 0x0001,
kHardwareCursorDescriptorMinorVersion = 0x0000
};
struct HardwareCursorDescriptorRec {
UInt16 majorVersion;
UInt16 minorVersion;
UInt32 height;
UInt32 width;
UInt32 bitDepth;
UInt32 maskBitDepth;
UInt32 numColors;
UInt32 *colorEncodings;
UInt32 flags;
UInt32 supportedSpecialEncodings;
UInt32 specialEncodings[16];
};
typedef struct HardwareCursorDescriptorRec HardwareCursorDescriptorRec,
*HardwareCursorDescriptorPtr;
The majorVersion and minorVersion fields describe the version of the descriptor record. The driver must set these to kHardwareCursorDescriptorMajorVersion and kHardwareCursorDescriptorMinorVersion. Doing so will provide compatibility with the conversion routine if the descriptor is changed in future releases of the VSL.
The height and width fields specify the maximum cursor height and width, in pixels, supported by the hardware.
The bitDepth field specifies the bit depth of the hardware cursor.
The maskBitDepth field is currently unused but reserved for future use. The driver must set this field to 0.
The numColors field specifies the number of colors supported by the hardware.
The colorEncodings field points to an array that specifies the hardware pixel encodings that map to the colors in the hardware cursor color table. The first entry in this array specifies the hardware cursor pixel value that corresponds to the first entry in the hardware cursor's color table; the second entry in this array specifies the pixel value for the second entry in the hardware's color table, and so on.
The flags field is used for extra information about the hardware. Currently, all flag bits are reserved and must be set to 0.
The supportedSpecialEncodings field specifies the type of special pixels supported by the hardware cursor and how they're implemented.
The special pixel types supported by the descriptor are transparent pixels and inverting pixels. Transparent pixels are invisible, and the frame buffer pixel underneath a transparent hardware cursor pixel is seen. Inverting hardware cursor pixels invert the frame buffer pixel underneath.
The specialEncodings field is an array that specifies the pixel values for special encodings. Use the constants kTransparentEncoding and kInvertingEncoding to index into the array.
The following hardware descriptor specifies a typical two-color hardware cursor:
UInt32 cursorColorEncodings[] =
{
0, 1
};
HardwareCursorDescriptorRec hardwareCursorDescriptor =
{
kHardwareCursorDescriptorMajorVersion, // major version number
kHardwareCursorDescriptorMinorVersion, // minor version number
32, // height
32, // width
2, // pixel depth
0, // mask depth
2, // number of cursor colors
&cursorColorEncodings, // color pixel encodings
0, // flags
kTransparentEncodedPixel | // supports transparent pixels
kInvertingEncodedPixel, // supports inverting pixels
2, // transparent pixel encoding
3, // inverting pixel encoding
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 // unused encodings
}
The foregoing describes a 2-bit-per-pixel hardware cursor that can be up to 32 by 32 pixels in size and supports transparent and inverting pixels. A cursor pixel value of 0 will display the first color in the cursor's color map, and a pixel value of 1 will display the second color. A cursor pixel value of 2 will display the color of the screen pixel underneath the cursor. A cursor pixel value of 3 will display the inverse of the color of the screen pixel underneath the cursor.
The following hardware descriptor describes a three-color hardware cursor:
UInt32 cursorColorEncodings[] =
{
1, 2, 3
};
HardwareCursorDescriptorRec hardwareCursorDescriptor =
{
kHardwareCursorDescriptorMajorVersion, // major version number
kHardwareCursorDescriptorMinorVersion, // minor version number
32, // height
32, // width
2, // pixel depth
0, // mask depth
3, // number of cursor colors
&cursorColorEncodings, // color pixel encodings
0, // flags
kTransparentEncodedPixel, // supports transparent pixels
0, // transparent pixel encoding
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 // unused encodings
};
The foregoing describes a 2-bit-per-pixel hardware cursor that can be up to 32 by 32 pixels in size and supports transparent pixels. A cursor pixel value of 1 displays the first color in the cursor's color map, a pixel value of 2 displays the second color, and a pixel value of 3 displays the third color. A cursor pixel value of 0 displays the color of the screen pixel underneath the cursor. If the cursor requires inverting pixels (for example, the I-beam text edit cursor), a call to VSLPrepareCursorForHardwareCursor will return false and the driver should let the cursor be implemented in software.
The VSLPrepareCursorForHardwareCursor call will return the information that the driver needs to program the hardware cursor in the following data structure:
enum {
kHardwareCursorInfoMajorVersion = 0x0001,
kHardwareCursorInfoMinorVersion = 0x0000
};
struct HardwareCursorInfoRec {
UInt16 majorVersion;
UInt16 minorVersion;
UInt32 cursorHeight;
UInt32 cursorWidth;
CTabPtr colorMap;
Ptr hardwareCursor;
UInt32 reserved[6];
};
typedef struct HardwareCursorInfoRec HardwareCursorInfoRec,
*HardwareCursorInfoPtr;
The majorVersion and minorVersion fields describe what version of the info record is being used. The driver must set these to kHardwareCursorInfoMajorVersion and kHardwareCursorInfoMinorVersion. Doing so will provide compatibility with the conversion routine if the descriptor is changed in future releases of the VSL.
The cursorHeight and cursorWidth fields specify the height and width of the cursor passed in from QuickDraw.
The colorMap field is the table of colors that the cursor uses. A table big enough to hold all of the colors supported by the hardware cursor must be passed to the VSLPrepareCursorForHardwareCursor call, which will fill this table with the appropriate colors. These colors are taken from the color table in the gDevice record for the driver's display. The driver must perform any required gamma correction on this color table.
The hardwareCursor field points to the buffer containing the converted image for the hardware cursor. A buffer big enough to hold the largest cursor supported by the hardware must be passed to the VSLPrepareCursorForHardwareCursor call, which will fill this buffer with the appropriate pixel values. The conversion call will not necessarily fill the entire buffer if the cursor passed from QuickDraw is smaller than the largest cursor supported by the hardware. The hardwareCursor buffer image's row bytes will equal cursorWidth times the pixel depth of the hardware cursor. The driver must set the extra pixels to be transparent.
The reserved field is an array of reserved values, and the driver must set these to 0.