[deb_xorg-server.git] / hw / xfree86 / ramdac / CURSOR.NOTES

			CURSOR.NOTES

  This file describes how to add hardware cursor support to a chipset
driver.  Though the cursor support itself is in the ramdac module,
cursor management is separate from the rest of the module.


1) CURSOR INITIALIZATION AND SHUTDOWN

   All relevant prototypes and defines are in xf86Cursor.h.

  To initialize the cursor, the driver should allocate an 
xf86CursorInfoRec via xf86CreateCursorInfoRec(), fill it out as described 
later in this  document and pass it to xf86InitCursor().  xf86InitCursor() 
must be called _after_ the software cursor initialization (usually
miDCInitialize).

   When shutting down, the driver should free the xf86CursorInfoRec
structure in its CloseScreen function via xf86DestroyCursorInfoRec().


2) FILLING OUT THE xf86CursorInfoRec

   The driver informs the ramdac module of it's hardware cursor capablities by
filling out an xf86CursorInfoRec structure and passing it to xf86InitCursor().
The xf86CursorInfoRec contains the following function pointers:


/**** These functions are required ****/

void ShowCursor(ScrnInfoPtr pScrn)

    ShowCursor should display the current cursor.

void HideCursor(ScrnInfoPtr pScrn)

    HideCursor should hide the current cursor.

void SetCursorPosition(ScrnInfoPtr pScrn, int x, int y)

    Set the cursor position to (x,y).  X and/or y may be negative
    indicating that the cursor image is partially offscreen on
    the left and/or top edges of the screen.  It is up to the
    driver to trap for this and deal with that situation.

void SetCursorColors(ScrnInfoPtr pScrn, int bg, int fg)

    Set the cursor foreground and background colors.  In 8bpp, fg and
    bg are indicies into the current colormap unless the 
    HARDWARE_CURSOR_TRUECOLOR_AT_8BPP flag is set.  In that case
    and in all other bpps the fg and bg are in 8-8-8 RGB format.
    
void LoadCursorImage(ScrnInfoPtr pScrn, unsigned char *bits)

    LoadCursorImage is how the hardware cursor bits computed by the
    RealizeCursor function will be passed to the driver when the cursor
    shape needs to be changed.


/**** These functions are optional ****/

    
unsigned char* RealizeCursor(xf86CursorInfoPtr infoPtr, CursorPtr pCurs) 

    If RealizeCursor is not provided by the driver, one will be provided
    for you based on the Flags field described below.  The driver must
    provide this function if the hardware cursor format is not one of
    the common ones supported by this module.
  

Bool UseHWCursor(ScreenPtr pScreen, CursorPtr pCurs)

    If the driver is unable to use a hardware cursor for reasons
    other than the cursor being larger than the maximum specified
    in the MaxWidth or MaxHeight field below, it can supply the
    UseHWCursor function.  If UseHWCursor is provided by the driver,
    it will be called whenever the cursor shape changes or the video
    mode changes.  This is useful for when the hardware cursor cannot
    be used in interlaced or doublescan modes.


/**** The following fields are required ****/

MaxWidth
MaxHeight

    These indicate the largest sized cursor that can be a hardware
    cursor.  It will fall back to a software cursor when a cursor
    exceeding this size needs to be used.


Flags

   /* Color related flags */

   HARDWARE_CURSOR_TRUECOLOR_AT_8BPP

   This indicates that the colors passed to the SetCursorColors
   function should not be in 8-8-8 RGB format in 8bpp but rather,
   they should be the pixel values from the current colormap.


   /* Cursor data loading flags */

   HARDWARE_CURSOR_SHOW_TRANSPARENT

   The HideCursor entry will normally be called instead of displaying a
   completely transparent cursor, or when a switch to a software cursor
   needs to occur.  This flag prevents this behaviour, thus causing the
   LoadCursorImage entry to be called with transparent cursor data.
   NOTE:  If you use this flag and provide your own RealizeCursor() entry,
          ensure this entry returns transparent cursor data when called
          with a NULL pCurs parameter.

   HARDWARE_CURSOR_UPDATE_UNHIDDEN

   This flag prevents the HideCursor call that would normally occur just before
   the LoadCursorImage entry is to be called to load a new hardware cursor
   image.


   /* Cursor data packing flags */

   Hardware cursor data consists of two pieces, a source and a mask.
   The mask is a bitmap indicating which parts of the cursor are 
   transparent and which parts are drawn.  The source is a bitmap
   indicating which parts of the non-transparent portion of the the
   cursor should be painted in the foreground color and which should
   be painted in the background color.

   HARDWARE_CURSOR_INVERT_MASK

   By default, set bits indicate the opaque part of the mask bitmap
   and clear bits indicate the transparent part.  If your hardware
   wants this the opposite way, this flag will invert the mask.

   HARDWARE_CURSOR_SWAP_SOURCE_AND_MASK

   By default, RealizeCursor will store the source first and then
   the mask.  If the hardware needs this order reversed then this
   flag should be set.

   HARDWARE_CURSOR_AND_SOURCE_WITH_MASK

   This flag will have the module logical AND the source with the mask to make  
   sure there are no source bits set if the corresponding mask bits 
   aren't set.  Some hardware will not care if source bits are set where
   there are supposed to be transparent areas, but some hardware will
   interpret this as a third cursor color or similar.  That type of
   hardware will need this flag set.

   HARDWARE_CURSOR_BIT_ORDER_MSBFIRST

   By default, it is assumed that the least significant bit in each byte
   corresponds to the leftmost pixel on the screen.  If your hardware
   has this reversed you should set this flag.

   HARDWARE_CURSOR_NIBBLE_SWAPPED

   If your hardware requires byte swapping of the hardware cursor, enable
   this option.


   /* Source-Mask interleaving flags */

   By default the source and mask data are inlined (source first unless
   the HARDWARE_CURSOR_SWAP_SOURCE_AND_MASK flag is set).  Some hardware
   will require the source and mask to be interleaved, that is, X number
   of source bits should packed and then X number of mask bits repeating
   until the entire pattern is stored.  The following flags describe the
   bit interleave.

   HARDWARE_CURSOR_SOURCE_MASK_NOT_INTERLEAVED   

   This one is the default.
 
   The following are for interleaved cursors.
    
   HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_1        
   HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_8        
   HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_16       
   HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_32       
   HARDWARE_CURSOR_SOURCE_MASK_INTERLEAVE_64   

   And once again, if your hardware requires something different than
   these packing styles, your driver can supply its own RealizeCursor
   function.   


$XFree86: xc/programs/Xserver/hw/xfree86/ramdac/CURSOR.NOTES,v 1.4tsi Exp $
Commit	Line	Data
a09e091a JB	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 $