CURSOR.NOTES (6864B)
1 CURSOR.NOTES 2 3 This file describes how to add hardware cursor support to a chipset 4 driver. Though the cursor support itself is in the ramdac module, 5 cursor management is separate from the rest of the module. 6 7 8 1) CURSOR INITIALIZATION AND SHUTDOWN 9 10 All relevant prototypes and defines are in xf86Cursor.h. 11 12 To initialize the cursor, the driver should allocate an 13 xf86CursorInfoRec via xf86CreateCursorInfoRec(), fill it out as described 14 later in this document and pass it to xf86InitCursor(). xf86InitCursor() 15 must be called _after_ the software cursor initialization (usually 16 miDCInitialize). 17 18 When shutting down, the driver should free the xf86CursorInfoRec 19 structure in its CloseScreen function via xf86DestroyCursorInfoRec(). 20 21 22 2) FILLING OUT THE xf86CursorInfoRec 23 24 The driver informs the ramdac module of its hardware cursor capabilities by 25 filling out an xf86CursorInfoRec structure and passing it to xf86InitCursor(). 26 The xf86CursorInfoRec contains the following function pointers: 27 28 29 /**** These functions are required ****/ 30 31 void ShowCursor(ScrnInfoPtr pScrn) 32 33 ShowCursor should display the current cursor. 34 35 void HideCursor(ScrnInfoPtr pScrn) 36 37 HideCursor should hide the current cursor. 38 39 void SetCursorPosition(ScrnInfoPtr pScrn, int x, int y) 40 41 Set the cursor position to (x,y). X and/or y may be negative 42 indicating that the cursor image is partially offscreen on 43 the left and/or top edges of the screen. It is up to the 44 driver to trap for this and deal with that situation. 45 46 void SetCursorColors(ScrnInfoPtr pScrn, int bg, int fg) 47 48 Set the cursor foreground and background colors. In 8bpp, fg and 49 bg are indices into the current colormap unless the 50 HARDWARE_CURSOR_TRUECOLOR_AT_8BPP flag is set. In that case 51 and in all other bpps the fg and bg are in 8-8-8 RGB format. 52 53 void LoadCursorImage(ScrnInfoPtr pScrn, unsigned char *bits) 54 55 LoadCursorImage is how the hardware cursor bits computed by the 56 RealizeCursor function will be passed to the driver when the cursor 57 shape needs to be changed. 58 59 60 /**** These functions are optional ****/ 61 62 63 unsigned char* RealizeCursor(xf86CursorInfoPtr infoPtr, CursorPtr pCurs) 64 65 If RealizeCursor is not provided by the driver, one will be provided 66 for you based on the Flags field described below. The driver must 67 provide this function if the hardware cursor format is not one of 68 the common ones supported by this module. 69 70 71 Bool UseHWCursor(ScreenPtr pScreen, CursorPtr pCurs) 72 73 If the driver is unable to use a hardware cursor for reasons 74 other than the cursor being larger than the maximum specified 75 in the MaxWidth or MaxHeight field below, it can supply the 76 UseHWCursor function. If UseHWCursor is provided by the driver, 77 it will be called whenever the cursor shape changes or the video 78 mode changes. This is useful for when the hardware cursor cannot 79 be used in interlaced or doublescan modes. 80 81 82 /**** The following fields are required ****/ 83 84 MaxWidth 85 MaxHeight 86 87 These indicate the largest sized cursor that can be a hardware 88 cursor. It will fall back to a software cursor when a cursor 89 exceeding this size needs to be used. 90 91 92 Flags 93 94 /* Color related flags */ 95 96 HARDWARE_CURSOR_TRUECOLOR_AT_8BPP 97 98 This indicates that the colors passed to the SetCursorColors 99 function should not be in 8-8-8 RGB format in 8bpp but rather, 100 they should be the pixel values from the current colormap. 101 102 103 /* Cursor data loading flags */ 104 105 HARDWARE_CURSOR_SHOW_TRANSPARENT 106 107 The HideCursor entry will normally be called instead of displaying a 108 completely transparent cursor, or when a switch to a software cursor 109 needs to occur. This flag prevents this behaviour, thus causing the 110 LoadCursorImage entry to be called with transparent cursor data. 111 NOTE: If you use this flag and provide your own RealizeCursor() entry, 112 ensure this entry returns transparent cursor data when called 113 with a NULL pCurs parameter. 114 115 HARDWARE_CURSOR_UPDATE_UNHIDDEN 116 117 This flag prevents the HideCursor call that would normally occur just before 118 the LoadCursorImage entry is to be called to load a new hardware cursor 119 image. 120 121 122 /* Cursor data packing flags */ 123 124 Hardware cursor data consists of two pieces, a source and a mask. 125 The mask is a bitmap indicating which parts of the cursor are 126 transparent and which parts are drawn. The source is a bitmap 127 indicating which parts of the non-transparent portion of the the 128 cursor should be painted in the foreground color and which should 129 be painted in the background color. 130 131 HARDWARE_CURSOR_INVERT_MASK 132 133 By default, set bits indicate the opaque part of the mask bitmap 134 and clear bits indicate the transparent part. If your hardware 135 wants this the opposite way, this flag will invert the mask. 136 137 HARDWARE_CURSOR_SWAP_SOURCE_AND_MASK 138 139 By default, RealizeCursor will store the source first and then 140 the mask. If the hardware needs this order reversed then this 141 flag should be set. 142 143 HARDWARE_CURSOR_AND_SOURCE_WITH_MASK 144 145 This flag will have the module logical AND the source with the mask to make 146 sure there are no source bits set if the corresponding mask bits 147 aren't set. Some hardware will not care if source bits are set where 148 there are supposed to be transparent areas, but some hardware will 149 interpret this as a third cursor color or similar. That type of 150 hardware will need this flag set. 151 152 HARDWARE_CURSOR_BIT_ORDER_MSBFIRST 153 154 By default, it is assumed that the least significant bit in each byte 155 corresponds to the leftmost pixel on the screen. If your hardware 156 has this reversed you should set this flag. 157 158 HARDWARE_CURSOR_NIBBLE_SWAPPED 159 160 If your hardware requires byte swapping of the hardware cursor, enable 161 this option. 162 163 164 /* Source-Mask interleaving flags */ 165 166 By default the source and mask data are inlined (source first unless 167 the HARDWARE_CURSOR_SWAP_SOURCE_AND_MASK flag is set). Some hardware 168 will require the source and mask to be interleaved, that is, X number 169 of source bits should packed and then X number of mask bits repeating 170 until the entire pattern is stored. The following flags describe the 171 bit interleave. 172 173 HARDWARE_CURSOR_SOURCE_MASK_NOT_INTERLEAVED 174 175 This one is the default. 176 177 The following are for interleaved cursors. 178 179 HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_1 180 HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_8 181 HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_16 182 HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_32 183 HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_64 184 185 And once again, if your hardware requires something different than 186 these packing styles, your driver can supply its own RealizeCursor 187 function. 188 189 190 191 $XFree86: xc/programs/Xserver/hw/xfree86/ramdac/CURSOR.NOTES,v 1.4tsi Exp $