Document the restriction on PrepareAccess() failure, from discussion with

benh.

ChangeLog

@@ -1,3 +1,9 @@
+2006-03-09  Eric Anholt  <anholt@FreeBSD.org>
+
+	* exa/exa.h:
+	Document the restriction on PrepareAccess() failure, from discussion
+	with benh.
+
 2006-03-09  Jeremy C. Reed  <reed@reedmedia.net>
 
 	* hw/xfree86/common/xf86Configure.c:

exa/exa.h

@@ -598,12 +598,15 @@ typedef struct _ExaDriver {
      * within the same pixmap (so it gets PrepareAccess as EXA_PREPARE_DEST and
      * then as EXA_PREPARE_SRC).
      *
+     * PrepareAccess() may fail.  An example might be the case of hardware that
+     * can set up 1 or 2 surfaces for CPU access, but not 3.  If PrepareAccess
+     * fails, EXA will migrate the pixmap to system memory.  For this migration,
+     * DownloadFromScreen() must be implemented, and must not fail.
+     * PrepareAccess() must not fail when pPix is the visible screen, because
+     * the visible screen can not be migrated.
+     *
      * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU
-     * drawing.  Failure means that EXA should migrate the pixmap out of
+     * drawing.
-     * offscreen memory, but this code path is currently broken.  Note that
-     * DownloadFromScreen() will be called in case of a PrepareAccess() failure.
-     * Also, PrepareAccess() may not fail on a pixmap representing the front
-     * buffer, because the front buffer may not be migrated.
      */
     Bool	(*PrepareAccess)(PixmapPtr pPix, int index);