intel: Define enum intel_dri2_has_hiz

... which indicates if the X driver supports DRI2BufferHiz and
DRI2BufferStencil.

I'm placing this in its own commit due to the large comment block.

CC: Ian Romanick <idr@freedesktop.org>
CC: Kristian Høgsberg <krh@bitplanet.net>
Acked-by: Eric Anholt <eric@anholt.net>
Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
Signed-off-by: Chad Versace <chad@chad-versace.us>

src/mesa/drivers/dri/intel/intel_screen.h

@@ -34,6 +34,62 @@
 #include "i915_drm.h"
 #include "xmlconfig.h"
 
+/**
+ * \brief Does X driver support DRI2BufferHiz and DRI2BufferStencil?
+ *
+ * (Here, "X driver" referes to the DDX driver, xf86-video-intel).
+ *
+ * The DRI2 protocol does not allow us to query the X driver's version nor
+ * query for a list of buffer formats that the driver supports. So, to
+ * determine if the X driver supports DRI2BufferHiz and DRI2BufferStencil we
+ * must resort to a handshake.
+ *
+ * If the hardware lacks support for separate stencil (and consequently, lacks
+ * support for hiz also), then the X driver's separate stencil and hiz support
+ * is irrelevant and the handshake never occurs.
+ *
+ * Complications
+ * -------------
+ * The handshake is complicated by a bug in xf86-video-intel 2.15. Even though
+ * that version of the X driver did not supppot requests for DRI2BufferHiz or
+ * DRI2BufferStencil, if requested one it still allocated and returned one.
+ * The returned buffer, however, was incorrectly X tiled.
+ *
+ * How the handshake works
+ * -----------------------
+ * (TODO: To be implemented on a future commit).
+ *
+ * Initially, intel_screen.dri2_has_hiz is set to unknown. The first time the
+ * user requests a depth and stencil buffer, intelCreateBuffers() creates a
+ * framebuffer with separate depth and stencil attachments (with formats
+ * x8_z24 and s8).
+ *
+ * Eventually, intel_update_renderbuffers() makes a DRI2 request for
+ * DRI2BufferStencil and DRI2BufferHiz. If the returned buffers are Y tiled,
+ * then we joyfully set intel_screen.dri2_has_hiz to true and continue as if
+ * nothing happend.
+ *
+ * If the buffers are X tiled, however, the handshake has failed and we must
+ * clean up.
+ *    1. Angrily set intel_screen.dri2_has_hiz to false.
+ *    2. Discard the framebuffer's depth and stencil attachments.
+ *    3. Attach a packed depth/stencil buffer to the framebuffer (with format
+ *       s8_z24).
+ *    4. Make a DRI2 request for the new buffer, using attachment type
+ *       DRI2BufferDepthStencil).
+ *
+ * Future Considerations
+ * ---------------------
+ * On a sunny day in the far future, when we are certain that no one has an
+ * xf86-video-intel installed without hiz and separate stencil support, then
+ * this enumerant and the handshake should die.
+ */
+enum intel_dri2_has_hiz {
+   INTEL_DRI2_HAS_HIZ_UNKNOWN,
+   INTEL_DRI2_HAS_HIZ_TRUE,
+   INTEL_DRI2_HAS_HIZ_FALSE,
+};
+
 struct intel_screen
 {
    int deviceID;