1			CURSOR.NOTES
2
3  This file describes how to add hardware cursor support to a chipset
4driver.  Though the cursor support itself is in the ramdac module,
5cursor management is separate from the rest of the module.
6
7
81) 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
13xf86CursorInfoRec via xf86CreateCursorInfoRec(), fill it out as described
14later in this  document and pass it to xf86InitCursor().  xf86InitCursor()
15must be called _after_ the software cursor initialization (usually
16miDCInitialize).
17
18   When shutting down, the driver should free the xf86CursorInfoRec
19structure in its CloseScreen function via xf86DestroyCursorInfoRec().
20
21
222) FILLING OUT THE xf86CursorInfoRec
23
24   The driver informs the ramdac module of it's hardware cursor capablities by
25filling out an xf86CursorInfoRec structure and passing it to xf86InitCursor().
26The xf86CursorInfoRec contains the following function pointers:
27
28
29/**** These functions are required ****/
30
31void ShowCursor(ScrnInfoPtr pScrn)
32
33    ShowCursor should display the current cursor.
34
35void HideCursor(ScrnInfoPtr pScrn)
36
37    HideCursor should hide the current cursor.
38
39void 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
46void 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
53void 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
63unsigned 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
71Bool 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
84MaxWidth
85MaxHeight
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
92Flags
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 $
192