From 9cec35579c91fc5b24607e1b0de2562b29bbc6ba Mon Sep 17 00:00:00 2001
From: Jason Ekstrand <jason.ekstrand@intel.com>
Date: Thu, 17 Aug 2017 19:05:30 -0700
Subject: [PATCH] intel/common: Improve the comments for sample positions

These are pulled directly from brw_multisample_state.h

Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
---
 src/intel/common/gen_sample_positions.h | 65 +++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/src/intel/common/gen_sample_positions.h b/src/intel/common/gen_sample_positions.h
index b86a7d84366..f0ce95dd1fb 100644
--- a/src/intel/common/gen_sample_positions.h
+++ b/src/intel/common/gen_sample_positions.h
@@ -23,16 +23,38 @@
 #ifndef GEN_SAMPLE_POSITIONS_H
 #define GEN_SAMPLE_POSITIONS_H
 
+/*
+ * This file defines the standard multisample positions used by both GL and
+ * Vulkan.  These correspond to the Vulkan "standard sample locations".
+ */
+
+/**
+ * 1x MSAA has a single sample at the center: (0.5, 0.5) -> (0x8, 0x8).
+ */
 #define GEN_SAMPLE_POS_1X(prefix) \
 prefix##0XOffset   = 0.5; \
 prefix##0YOffset   = 0.5;
 
+/**
+ * 2x MSAA sample positions are (0.25, 0.25) and (0.75, 0.75):
+ *   4 c
+ * 4 0
+ * c   1
+ */
 #define GEN_SAMPLE_POS_2X(prefix) \
 prefix##0XOffset   = 0.25; \
 prefix##0YOffset   = 0.25; \
 prefix##1XOffset   = 0.75; \
 prefix##1YOffset   = 0.75;
 
+/**
+ * Sample positions:
+ *   2 6 a e
+ * 2   0
+ * 6       1
+ * a 2
+ * e     3
+ */
 #define GEN_SAMPLE_POS_4X(prefix) \
 prefix##0XOffset   = 0.375; \
 prefix##0YOffset   = 0.125; \
@@ -43,6 +65,28 @@ prefix##2YOffset   = 0.625; \
 prefix##3XOffset   = 0.625; \
 prefix##3YOffset   = 0.875;
 
+/**
+ * Sample positions:
+ *
+ * From the Ivy Bridge PRM, Vol2 Part1 p304 (3DSTATE_MULTISAMPLE:
+ * Programming Notes):
+ *     "When programming the sample offsets (for NUMSAMPLES_4 or _8 and
+ *     MSRASTMODE_xxx_PATTERN), the order of the samples 0 to 3 (or 7
+ *     for 8X) must have monotonically increasing distance from the
+ *     pixel center. This is required to get the correct centroid
+ *     computation in the device."
+ *
+ * Sample positions:
+ *   1 3 5 7 9 b d f
+ * 1               7
+ * 3     3
+ * 5         0
+ * 7 5
+ * 9             2
+ * b       1
+ * d   4
+ * f           6
+ */
 #define GEN_SAMPLE_POS_8X(prefix) \
 prefix##0XOffset   = 0.5625; \
 prefix##0YOffset   = 0.3125; \
@@ -61,6 +105,27 @@ prefix##6YOffset   = 0.9375; \
 prefix##7XOffset   = 0.9375; \
 prefix##7YOffset   = 0.0625;
 
+/**
+ * Sample positions:
+ *
+ *    0 1 2 3 4 5 6 7 8 9 a b c d e f
+ * 0   15
+ * 1                  9
+ * 2         10
+ * 3                        7
+ * 4                               13
+ * 5                1
+ * 6        4
+ * 7                          3
+ * 8 12
+ * 9                    0
+ * a            2
+ * b                            6
+ * c     11
+ * d                      5
+ * e              8
+ * f                             14
+ */
 #define GEN_SAMPLE_POS_16X(prefix) \
 prefix##0XOffset   = 0.5625; \
 prefix##0YOffset   = 0.5625; \
-- 
2.30.2