← Back to branch summary

~ubuntu-branches/ubuntu/intrepid/xserver-xgl/intrepid

« back to all changes in this revision

Viewing changes to hw/xfree86/ramdac/CURSOR.NOTES

  • Committer: Bazaar Package Importer
  • Author(s): Matthew Garrett
  • Date: 2006-02-13 14:21:43 UTC
  • Revision ID: james.westby@ubuntu.com-20060213142143-mad6z9xzem7hzxz9
Tags: upstream-7.0.0
Import upstream version 7.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
hw/xfree86/ramdac/CURSOR.NOTES
 
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 $