| 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 it's hardware cursor capablities 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 indicies 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 $ |