src/vulkan/isl.h

   1 /*
   2  * Copyright 2015 Intel Corporation
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the "Software"),
   6  * to deal in the Software without restriction, including without limitation
   7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8  * and/or sell copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice (including the next
  12  * paragraph) shall be included in all copies or substantial portions of the
  13  * Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  21  * IN THE SOFTWARE.
  22  */
  23
  24 /**
  25  * @file
  26  * @brief Intel Surface Layout
  27  *
  28  * Header Layout
  29  * =============
  30  *
  31  * The header is ordered as:
  32  *    - forward declarations
  33  *    - macros that may be overridden at compile-time for specific gens
  34  *    - enums and constants
  35  *    - structs and unions
  36  *    - functions
  37  *
  38  *
  39  * Surface Units
  40  * =============
  41  *
  42  * Some symbol names have a unit suffix.
  43  *
  44  *    - px: logical pixels
  45  *    - sa: physical surface samples
  46  *    - el: physical surface elements
  47  *    - sa_rows: rows of physical surface samples
  48  *    - el_rows: rows of physical surface elements
  49  *
  50  * The Broadwell PRM [1] defines a surface element as follows:
  51  *
  52  *    An element is defined as a pixel in uncompresed surface formats, and as
  53  *    a compression block in compressed surface formats. For
  54  *    MSFMT_DEPTH_STENCIL type multisampled surfaces, an element is a sample.
  55  *
  56  * [1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >>
  57  *      RENDER_SURFACE_STATE Surface Vertical Alignment (p325)
  58  */
  59
  60 #pragma once
  61
  62 #include <assert.h>
  63 #include <stdbool.h>
  64 #include <stdint.h>
  65
  66 #include "util/macros.h"
  67
  68 #ifdef __cplusplus
  69 extern "C" {
  70 #endif
  71
  72 struct brw_device_info;
  73 struct brw_image_param;
  74
  75 #ifndef ISL_DEV_GEN
  76 /**
  77  * @brief Get the hardware generation of isl_device.
  78  *
  79  * You can define this as a compile-time constant in the CFLAGS. For example,
  80  * `gcc -DISL_DEV_GEN(dev)=9 ...`.
  81  */
  82 #define ISL_DEV_GEN(__dev) ((__dev)->info->gen)
  83 #endif
  84
  85 #ifndef ISL_DEV_USE_SEPARATE_STENCIL
  86 /**
  87  * You can define this as a compile-time constant in the CFLAGS. For example,
  88  * `gcc -DISL_DEV_USE_SEPARATE_STENCIL(dev)=1 ...`.
  89  */
  90 #define ISL_DEV_USE_SEPARATE_STENCIL(__dev) ((__dev)->use_separate_stencil)
  91 #endif
  92
  93 /**
  94  * Hardware enumeration SURFACE_FORMAT.
  95  *
  96  * For the official list, see Broadwell PRM: Volume 2b: Command Reference:
  97  * Enumerations: SURFACE_FORMAT.
  98  */
  99 enum isl_format {
 100    ISL_FORMAT_R32G32B32A32_FLOAT =                               0,
 101    ISL_FORMAT_R32G32B32A32_SINT =                                1,
 102    ISL_FORMAT_R32G32B32A32_UINT =                                2,
 103    ISL_FORMAT_R32G32B32A32_UNORM =                               3,
 104    ISL_FORMAT_R32G32B32A32_SNORM =                               4,
 105    ISL_FORMAT_R64G64_FLOAT =                                     5,
 106    ISL_FORMAT_R32G32B32X32_FLOAT =                               6,
 107    ISL_FORMAT_R32G32B32A32_SSCALED =                             7,
 108    ISL_FORMAT_R32G32B32A32_USCALED =                             8,
 109    ISL_FORMAT_R32G32B32A32_SFIXED =                             32,
 110    ISL_FORMAT_R64G64_PASSTHRU =                                 33,
 111    ISL_FORMAT_R32G32B32_FLOAT =                                 64,
 112    ISL_FORMAT_R32G32B32_SINT =                                  65,
 113    ISL_FORMAT_R32G32B32_UINT =                                  66,
 114    ISL_FORMAT_R32G32B32_UNORM =                                 67,
 115    ISL_FORMAT_R32G32B32_SNORM =                                 68,
 116    ISL_FORMAT_R32G32B32_SSCALED =                               69,
 117    ISL_FORMAT_R32G32B32_USCALED =                               70,
 118    ISL_FORMAT_R32G32B32_SFIXED =                                80,
 119    ISL_FORMAT_R16G16B16A16_UNORM =                             128,
 120    ISL_FORMAT_R16G16B16A16_SNORM =                             129,
 121    ISL_FORMAT_R16G16B16A16_SINT =                              130,
 122    ISL_FORMAT_R16G16B16A16_UINT =                              131,
 123    ISL_FORMAT_R16G16B16A16_FLOAT =                             132,
 124    ISL_FORMAT_R32G32_FLOAT =                                   133,
 125    ISL_FORMAT_R32G32_SINT =                                    134,
 126    ISL_FORMAT_R32G32_UINT =                                    135,
 127    ISL_FORMAT_R32_FLOAT_X8X24_TYPELESS =                       136,
 128    ISL_FORMAT_X32_TYPELESS_G8X24_UINT =                        137,
 129    ISL_FORMAT_L32A32_FLOAT =                                   138,
 130    ISL_FORMAT_R32G32_UNORM =                                   139,
 131    ISL_FORMAT_R32G32_SNORM =                                   140,
 132    ISL_FORMAT_R64_FLOAT =                                      141,
 133    ISL_FORMAT_R16G16B16X16_UNORM =                             142,
 134    ISL_FORMAT_R16G16B16X16_FLOAT =                             143,
 135    ISL_FORMAT_A32X32_FLOAT =                                   144,
 136    ISL_FORMAT_L32X32_FLOAT =                                   145,
 137    ISL_FORMAT_I32X32_FLOAT =                                   146,
 138    ISL_FORMAT_R16G16B16A16_SSCALED =                           147,
 139    ISL_FORMAT_R16G16B16A16_USCALED =                           148,
 140    ISL_FORMAT_R32G32_SSCALED =                                 149,
 141    ISL_FORMAT_R32G32_USCALED =                                 150,
 142    ISL_FORMAT_R32G32_SFIXED =                                  160,
 143    ISL_FORMAT_R64_PASSTHRU =                                   161,
 144    ISL_FORMAT_B8G8R8A8_UNORM =                                 192,
 145    ISL_FORMAT_B8G8R8A8_UNORM_SRGB =                            193,
 146    ISL_FORMAT_R10G10B10A2_UNORM =                              194,
 147    ISL_FORMAT_R10G10B10A2_UNORM_SRGB =                         195,
 148    ISL_FORMAT_R10G10B10A2_UINT =                               196,
 149    ISL_FORMAT_R10G10B10_SNORM_A2_UNORM =                       197,
 150    ISL_FORMAT_R8G8B8A8_UNORM =                                 199,
 151    ISL_FORMAT_R8G8B8A8_UNORM_SRGB =                            200,
 152    ISL_FORMAT_R8G8B8A8_SNORM =                                 201,
 153    ISL_FORMAT_R8G8B8A8_SINT =                                  202,
 154    ISL_FORMAT_R8G8B8A8_UINT =                                  203,
 155    ISL_FORMAT_R16G16_UNORM =                                   204,
 156    ISL_FORMAT_R16G16_SNORM =                                   205,
 157    ISL_FORMAT_R16G16_SINT =                                    206,
 158    ISL_FORMAT_R16G16_UINT =                                    207,
 159    ISL_FORMAT_R16G16_FLOAT =                                   208,
 160    ISL_FORMAT_B10G10R10A2_UNORM =                              209,
 161    ISL_FORMAT_B10G10R10A2_UNORM_SRGB =                         210,
 162    ISL_FORMAT_R11G11B10_FLOAT =                                211,
 163    ISL_FORMAT_R32_SINT =                                       214,
 164    ISL_FORMAT_R32_UINT =                                       215,
 165    ISL_FORMAT_R32_FLOAT =                                      216,
 166    ISL_FORMAT_R24_UNORM_X8_TYPELESS =                          217,
 167    ISL_FORMAT_X24_TYPELESS_G8_UINT =                           218,
 168    ISL_FORMAT_L32_UNORM =                                      221,
 169    ISL_FORMAT_A32_UNORM =                                      222,
 170    ISL_FORMAT_L16A16_UNORM =                                   223,
 171    ISL_FORMAT_I24X8_UNORM =                                    224,
 172    ISL_FORMAT_L24X8_UNORM =                                    225,
 173    ISL_FORMAT_A24X8_UNORM =                                    226,
 174    ISL_FORMAT_I32_FLOAT =                                      227,
 175    ISL_FORMAT_L32_FLOAT =                                      228,
 176    ISL_FORMAT_A32_FLOAT =                                      229,
 177    ISL_FORMAT_X8B8_UNORM_G8R8_SNORM =                          230,
 178    ISL_FORMAT_A8X8_UNORM_G8R8_SNORM =                          231,
 179    ISL_FORMAT_B8X8_UNORM_G8R8_SNORM =                          232,
 180    ISL_FORMAT_B8G8R8X8_UNORM =                                 233,
 181    ISL_FORMAT_B8G8R8X8_UNORM_SRGB =                            234,
 182    ISL_FORMAT_R8G8B8X8_UNORM =                                 235,
 183    ISL_FORMAT_R8G8B8X8_UNORM_SRGB =                            236,
 184    ISL_FORMAT_R9G9B9E5_SHAREDEXP =                             237,
 185    ISL_FORMAT_B10G10R10X2_UNORM =                              238,
 186    ISL_FORMAT_L16A16_FLOAT =                                   240,
 187    ISL_FORMAT_R32_UNORM =                                      241,
 188    ISL_FORMAT_R32_SNORM =                                      242,
 189    ISL_FORMAT_R10G10B10X2_USCALED =                            243,
 190    ISL_FORMAT_R8G8B8A8_SSCALED =                               244,
 191    ISL_FORMAT_R8G8B8A8_USCALED =                               245,
 192    ISL_FORMAT_R16G16_SSCALED =                                 246,
 193    ISL_FORMAT_R16G16_USCALED =                                 247,
 194    ISL_FORMAT_R32_SSCALED =                                    248,
 195    ISL_FORMAT_R32_USCALED =                                    249,
 196    ISL_FORMAT_B5G6R5_UNORM =                                   256,
 197    ISL_FORMAT_B5G6R5_UNORM_SRGB =                              257,
 198    ISL_FORMAT_B5G5R5A1_UNORM =                                 258,
 199    ISL_FORMAT_B5G5R5A1_UNORM_SRGB =                            259,
 200    ISL_FORMAT_B4G4R4A4_UNORM =                                 260,
 201    ISL_FORMAT_B4G4R4A4_UNORM_SRGB =                            261,
 202    ISL_FORMAT_R8G8_UNORM =                                     262,
 203    ISL_FORMAT_R8G8_SNORM =                                     263,
 204    ISL_FORMAT_R8G8_SINT =                                      264,
 205    ISL_FORMAT_R8G8_UINT =                                      265,
 206    ISL_FORMAT_R16_UNORM =                                      266,
 207    ISL_FORMAT_R16_SNORM =                                      267,
 208    ISL_FORMAT_R16_SINT =                                       268,
 209    ISL_FORMAT_R16_UINT =                                       269,
 210    ISL_FORMAT_R16_FLOAT =                                      270,
 211    ISL_FORMAT_A8P8_UNORM_PALETTE0 =                            271,
 212    ISL_FORMAT_A8P8_UNORM_PALETTE1 =                            272,
 213    ISL_FORMAT_I16_UNORM =                                      273,
 214    ISL_FORMAT_L16_UNORM =                                      274,
 215    ISL_FORMAT_A16_UNORM =                                      275,
 216    ISL_FORMAT_L8A8_UNORM =                                     276,
 217    ISL_FORMAT_I16_FLOAT =                                      277,
 218    ISL_FORMAT_L16_FLOAT =                                      278,
 219    ISL_FORMAT_A16_FLOAT =                                      279,
 220    ISL_FORMAT_L8A8_UNORM_SRGB =                                280,
 221    ISL_FORMAT_R5G5_SNORM_B6_UNORM =                            281,
 222    ISL_FORMAT_B5G5R5X1_UNORM =                                 282,
 223    ISL_FORMAT_B5G5R5X1_UNORM_SRGB =                            283,
 224    ISL_FORMAT_R8G8_SSCALED =                                   284,
 225    ISL_FORMAT_R8G8_USCALED =                                   285,
 226    ISL_FORMAT_R16_SSCALED =                                    286,
 227    ISL_FORMAT_R16_USCALED =                                    287,
 228    ISL_FORMAT_P8A8_UNORM_PALETTE0 =                            290,
 229    ISL_FORMAT_P8A8_UNORM_PALETTE1 =                            291,
 230    ISL_FORMAT_A1B5G5R5_UNORM =                                 292,
 231    ISL_FORMAT_A4B4G4R4_UNORM =                                 293,
 232    ISL_FORMAT_L8A8_UINT =                                      294,
 233    ISL_FORMAT_L8A8_SINT =                                      295,
 234    ISL_FORMAT_R8_UNORM =                                       320,
 235    ISL_FORMAT_R8_SNORM =                                       321,
 236    ISL_FORMAT_R8_SINT =                                        322,
 237    ISL_FORMAT_R8_UINT =                                        323,
 238    ISL_FORMAT_A8_UNORM =                                       324,
 239    ISL_FORMAT_I8_UNORM =                                       325,
 240    ISL_FORMAT_L8_UNORM =                                       326,
 241    ISL_FORMAT_P4A4_UNORM_PALETTE0 =                            327,
 242    ISL_FORMAT_A4P4_UNORM_PALETTE0 =                            328,
 243    ISL_FORMAT_R8_SSCALED =                                     329,
 244    ISL_FORMAT_R8_USCALED =                                     330,
 245    ISL_FORMAT_P8_UNORM_PALETTE0 =                              331,
 246    ISL_FORMAT_L8_UNORM_SRGB =                                  332,
 247    ISL_FORMAT_P8_UNORM_PALETTE1 =                              333,
 248    ISL_FORMAT_P4A4_UNORM_PALETTE1 =                            334,
 249    ISL_FORMAT_A4P4_UNORM_PALETTE1 =                            335,
 250    ISL_FORMAT_Y8_UNORM =                                       336,
 251    ISL_FORMAT_L8_UINT =                                        338,
 252    ISL_FORMAT_L8_SINT =                                        339,
 253    ISL_FORMAT_I8_UINT =                                        340,
 254    ISL_FORMAT_I8_SINT =                                        341,
 255    ISL_FORMAT_DXT1_RGB_SRGB =                                  384,
 256    ISL_FORMAT_R1_UNORM =                                       385,
 257    ISL_FORMAT_YCRCB_NORMAL =                                   386,
 258    ISL_FORMAT_YCRCB_SWAPUVY =                                  387,
 259    ISL_FORMAT_P2_UNORM_PALETTE0 =                              388,
 260    ISL_FORMAT_P2_UNORM_PALETTE1 =                              389,
 261    ISL_FORMAT_BC1_UNORM =                                      390,
 262    ISL_FORMAT_BC2_UNORM =                                      391,
 263    ISL_FORMAT_BC3_UNORM =                                      392,
 264    ISL_FORMAT_BC4_UNORM =                                      393,
 265    ISL_FORMAT_BC5_UNORM =                                      394,
 266    ISL_FORMAT_BC1_UNORM_SRGB =                                 395,
 267    ISL_FORMAT_BC2_UNORM_SRGB =                                 396,
 268    ISL_FORMAT_BC3_UNORM_SRGB =                                 397,
 269    ISL_FORMAT_MONO8 =                                          398,
 270    ISL_FORMAT_YCRCB_SWAPUV =                                   399,
 271    ISL_FORMAT_YCRCB_SWAPY =                                    400,
 272    ISL_FORMAT_DXT1_RGB =                                       401,
 273    ISL_FORMAT_FXT1 =                                           402,
 274    ISL_FORMAT_R8G8B8_UNORM =                                   403,
 275    ISL_FORMAT_R8G8B8_SNORM =                                   404,
 276    ISL_FORMAT_R8G8B8_SSCALED =                                 405,
 277    ISL_FORMAT_R8G8B8_USCALED =                                 406,
 278    ISL_FORMAT_R64G64B64A64_FLOAT =                             407,
 279    ISL_FORMAT_R64G64B64_FLOAT =                                408,
 280    ISL_FORMAT_BC4_SNORM =                                      409,
 281    ISL_FORMAT_BC5_SNORM =                                      410,
 282    ISL_FORMAT_R16G16B16_FLOAT =                                411,
 283    ISL_FORMAT_R16G16B16_UNORM =                                412,
 284    ISL_FORMAT_R16G16B16_SNORM =                                413,
 285    ISL_FORMAT_R16G16B16_SSCALED =                              414,
 286    ISL_FORMAT_R16G16B16_USCALED =                              415,
 287    ISL_FORMAT_BC6H_SF16 =                                      417,
 288    ISL_FORMAT_BC7_UNORM =                                      418,
 289    ISL_FORMAT_BC7_UNORM_SRGB =                                 419,
 290    ISL_FORMAT_BC6H_UF16 =                                      420,
 291    ISL_FORMAT_PLANAR_420_8 =                                   421,
 292    ISL_FORMAT_R8G8B8_UNORM_SRGB =                              424,
 293    ISL_FORMAT_ETC1_RGB8 =                                      425,
 294    ISL_FORMAT_ETC2_RGB8 =                                      426,
 295    ISL_FORMAT_EAC_R11 =                                        427,
 296    ISL_FORMAT_EAC_RG11 =                                       428,
 297    ISL_FORMAT_EAC_SIGNED_R11 =                                 429,
 298    ISL_FORMAT_EAC_SIGNED_RG11 =                                430,
 299    ISL_FORMAT_ETC2_SRGB8 =                                     431,
 300    ISL_FORMAT_R16G16B16_UINT =                                 432,
 301    ISL_FORMAT_R16G16B16_SINT =                                 433,
 302    ISL_FORMAT_R32_SFIXED =                                     434,
 303    ISL_FORMAT_R10G10B10A2_SNORM =                              435,
 304    ISL_FORMAT_R10G10B10A2_USCALED =                            436,
 305    ISL_FORMAT_R10G10B10A2_SSCALED =                            437,
 306    ISL_FORMAT_R10G10B10A2_SINT =                               438,
 307    ISL_FORMAT_B10G10R10A2_SNORM =                              439,
 308    ISL_FORMAT_B10G10R10A2_USCALED =                            440,
 309    ISL_FORMAT_B10G10R10A2_SSCALED =                            441,
 310    ISL_FORMAT_B10G10R10A2_UINT =                               442,
 311    ISL_FORMAT_B10G10R10A2_SINT =                               443,
 312    ISL_FORMAT_R64G64B64A64_PASSTHRU =                          444,
 313    ISL_FORMAT_R64G64B64_PASSTHRU =                             445,
 314    ISL_FORMAT_ETC2_RGB8_PTA =                                  448,
 315    ISL_FORMAT_ETC2_SRGB8_PTA =                                 449,
 316    ISL_FORMAT_ETC2_EAC_RGBA8 =                                 450,
 317    ISL_FORMAT_ETC2_EAC_SRGB8_A8 =                              451,
 318    ISL_FORMAT_R8G8B8_UINT =                                    456,
 319    ISL_FORMAT_R8G8B8_SINT =                                    457,
 320    ISL_FORMAT_RAW =                                            511,
 321
 322    /* Hardware doesn't understand this out-of-band value */
 323    ISL_FORMAT_UNSUPPORTED =                             UINT16_MAX,
 324 };
 325
 326 /**
 327  * Numerical base type for channels of isl_format.
 328  */
 329 enum isl_base_type {
 330    ISL_VOID,
 331    ISL_RAW,
 332    ISL_UNORM,
 333    ISL_SNORM,
 334    ISL_UFLOAT,
 335    ISL_SFLOAT,
 336    ISL_UFIXED,
 337    ISL_SFIXED,
 338    ISL_UINT,
 339    ISL_SINT,
 340    ISL_USCALED,
 341    ISL_SSCALED,
 342 };
 343
 344 /**
 345  * Colorspace of isl_format.
 346  */
 347 enum isl_colorspace {
 348    ISL_COLORSPACE_NONE = 0,
 349    ISL_COLORSPACE_LINEAR,
 350    ISL_COLORSPACE_SRGB,
 351    ISL_COLORSPACE_YUV,
 352 };
 353
 354 /**
 355  * Texture compression mode of isl_format.
 356  */
 357 enum isl_txc {
 358    ISL_TXC_NONE = 0,
 359    ISL_TXC_DXT1,
 360    ISL_TXC_DXT3,
 361    ISL_TXC_DXT5,
 362    ISL_TXC_FXT1,
 363    ISL_TXC_RGTC1,
 364    ISL_TXC_RGTC2,
 365    ISL_TXC_BPTC,
 366    ISL_TXC_ETC1,
 367    ISL_TXC_ETC2,
 368 };
 369
 370 /**
 371  * @brief Hardware tile mode
 372  *
 373  * WARNING: These values differ from the hardware enum values, which are
 374  * unstable across hardware generations.
 375  *
 376  * Note that legacy Y tiling is ISL_TILING_Y0 instead of ISL_TILING_Y, to
 377  * clearly distinguish it from Yf and Ys.
 378  */
 379 enum isl_tiling {
 380    ISL_TILING_LINEAR = 0,
 381    ISL_TILING_W,
 382    ISL_TILING_X,
 383    ISL_TILING_Y0, /**< Legacy Y tiling */
 384    ISL_TILING_Yf,
 385    ISL_TILING_Ys,
 386 };
 387
 388 /**
 389  * @defgroup Tiling Flags
 390  * @{
 391  */
 392 typedef uint32_t isl_tiling_flags_t;
 393 #define ISL_TILING_LINEAR_BIT             (1u << ISL_TILING_LINEAR)
 394 #define ISL_TILING_W_BIT                  (1u << ISL_TILING_W)
 395 #define ISL_TILING_X_BIT                  (1u << ISL_TILING_X)
 396 #define ISL_TILING_Y0_BIT                 (1u << ISL_TILING_Y0)
 397 #define ISL_TILING_Yf_BIT                 (1u << ISL_TILING_Yf)
 398 #define ISL_TILING_Ys_BIT                 (1u << ISL_TILING_Ys)
 399 #define ISL_TILING_ANY_MASK               (~0u)
 400 #define ISL_TILING_NON_LINEAR_MASK        (~ISL_TILING_LINEAR_BIT)
 401
 402 /** Any Y tiling, including legacy Y tiling. */
 403 #define ISL_TILING_ANY_Y_MASK             (ISL_TILING_Y0_BIT | \
 404                                            ISL_TILING_Yf_BIT | \
 405                                            ISL_TILING_Ys_BIT)
 406
 407 /** The Skylake BSpec refers to Yf and Ys as "standard tiling formats". */
 408 #define ISL_TILING_STD_Y_MASK             (ISL_TILING_Yf_BIT | \
 409                                            ISL_TILING_Ys_BIT)
 410 /** @} */
 411
 412 /**
 413  * @brief Logical dimension of surface.
 414  *
 415  * Note: There is no dimension for cube map surfaces. ISL interprets cube maps
 416  * as 2D array surfaces.
 417  */
 418 enum isl_surf_dim {
 419    ISL_SURF_DIM_1D,
 420    ISL_SURF_DIM_2D,
 421    ISL_SURF_DIM_3D,
 422 };
 423
 424 /**
 425  * @brief Physical layout of the surface's dimensions.
 426  */
 427 enum isl_dim_layout {
 428    /**
 429     * For details, see the G35 PRM >> Volume 1: Graphics Core >> Section
 430     * 6.17.3: 2D Surfaces.
 431     *
 432     * On many gens, 1D surfaces share the same layout as 2D surfaces.  From
 433     * the G35 PRM >> Volume 1: Graphics Core >> Section 6.17.2: 1D Surfaces:
 434     *
 435     *    One-dimensional surfaces are identical to 2D surfaces with height of
 436     *    one.
 437     */
 438    ISL_DIM_LAYOUT_GEN4_2D,
 439
 440    /**
 441     * For details, see the G35 PRM >> Volume 1: Graphics Core >> Section
 442     * 6.17.5: 3D Surfaces.
 443     */
 444    ISL_DIM_LAYOUT_GEN4_3D,
 445
 446    /**
 447     * For details, see the Skylake BSpec >> Memory Views >> Common Surface
 448     * Formats >> Surface Layout and Tiling >> » 1D Surfaces.
 449     */
 450    ISL_DIM_LAYOUT_GEN9_1D,
 451 };
 452
 453 /* TODO(chadv): Explain */
 454 enum isl_array_pitch_span {
 455    ISL_ARRAY_PITCH_SPAN_FULL,
 456    ISL_ARRAY_PITCH_SPAN_COMPACT,
 457 };
 458
 459 /**
 460  * @defgroup Surface Usage
 461  * @{
 462  */
 463 typedef uint64_t isl_surf_usage_flags_t;
 464 #define ISL_SURF_USAGE_RENDER_TARGET_BIT       (1u << 0)
 465 #define ISL_SURF_USAGE_DEPTH_BIT               (1u << 1)
 466 #define ISL_SURF_USAGE_STENCIL_BIT             (1u << 2)
 467 #define ISL_SURF_USAGE_TEXTURE_BIT             (1u << 3)
 468 #define ISL_SURF_USAGE_CUBE_BIT                (1u << 4)
 469 #define ISL_SURF_USAGE_DISABLE_AUX_BIT         (1u << 5)
 470 #define ISL_SURF_USAGE_DISPLAY_BIT             (1u << 6)
 471 #define ISL_SURF_USAGE_DISPLAY_ROTATE_90_BIT   (1u << 7)
 472 #define ISL_SURF_USAGE_DISPLAY_ROTATE_180_BIT  (1u << 8)
 473 #define ISL_SURF_USAGE_DISPLAY_ROTATE_270_BIT  (1u << 9)
 474 #define ISL_SURF_USAGE_DISPLAY_FLIP_X_BIT      (1u << 10)
 475 #define ISL_SURF_USAGE_DISPLAY_FLIP_Y_BIT      (1u << 11)
 476 /** @} */
 477
 478 /**
 479  * @brief Multisample Format
 480  */
 481 enum isl_msaa_layout {
 482    /**
 483     * @brief Suface is single-sampled.
 484     */
 485    ISL_MSAA_LAYOUT_NONE,
 486
 487    /**
 488     * @brief [SNB+] Interleaved Multisample Format
 489     *
 490     * In this format, multiple samples are interleaved into each cacheline.
 491     * In other words, the sample index is swizzled into the low 6 bits of the
 492     * surface's virtual address space.
 493     *
 494     * For example, suppose the surface is legacy Y tiled, is 4x multisampled,
 495     * and its pixel format is 32bpp. Then the first cacheline is arranged
 496     * thus:
 497     *
 498     *    (0,0,0) (0,1,0)   (0,0,1) (1,0,1)
 499     *    (1,0,0) (1,1,0)   (0,1,1) (1,1,1)
 500     *
 501     *    (0,0,2) (1,0,2)   (0,0,3) (1,0,3)
 502     *    (0,1,2) (1,1,2)   (0,1,3) (1,1,3)
 503     *
 504     * The hardware docs refer to this format with multiple terms.  In
 505     * Sandybridge, this is the only multisample format; so no term is used.
 506     * The Ivybridge docs refer to surfaces in this format as IMS (Interleaved
 507     * Multisample Surface). Later hardware docs additionally refer to this
 508     * format as MSFMT_DEPTH_STENCIL (because the format is deprecated for
 509     * color surfaces).
 510     *
 511     * See the Sandybridge PRM, Volume 4, Part 1, Section 2.7 "Multisampled
 512     * Surface Behavior".
 513     *
 514     * See the Ivybridge PRM, Volume 1, Part 1, Section 6.18.4.1 "Interleaved
 515     * Multisampled Surfaces".
 516     */
 517    ISL_MSAA_LAYOUT_INTERLEAVED,
 518
 519    /**
 520     * @brief [IVB+] Array Multisample Format
 521     *
 522     * In this format, the surface's physical layout resembles that of a
 523     * 2D array surface.
 524     *
 525     * Suppose the multisample surface's logical extent is (w, h) and its
 526     * sample count is N. Then surface's physical extent is the same as
 527     * a singlesample 2D surface whose logical extent is (w, h) and array
 528     * length is N.  Array slice `i` contains the pixel values for sample
 529     * index `i`.
 530     *
 531     * The Ivybridge docs refer to surfaces in this format as UMS
 532     * (Uncompressed Multsample Layout) and CMS (Compressed Multisample
 533     * Surface). The Broadwell docs additionally refer to this format as
 534     * MSFMT_MSS (MSS=Multisample Surface Storage).
 535     *
 536     * See the Broadwell PRM, Volume 5 "Memory Views", Section "Uncompressed
 537     * Multisample Surfaces".
 538     *
 539     * See the Broadwell PRM, Volume 5 "Memory Views", Section "Compressed
 540     * Multisample Surfaces".
 541     */
 542    ISL_MSAA_LAYOUT_ARRAY,
 543 };
 544
 545
 546 struct isl_device {
 547    const struct brw_device_info *info;
 548    bool use_separate_stencil;
 549 };
 550
 551 struct isl_extent2d {
 552    union { uint32_t w, width; };
 553    union { uint32_t h, height; };
 554 };
 555
 556 struct isl_extent3d {
 557    union { uint32_t w, width; };
 558    union { uint32_t h, height; };
 559    union { uint32_t d, depth; };
 560 };
 561
 562 struct isl_extent4d {
 563    union { uint32_t w, width; };
 564    union { uint32_t h, height; };
 565    union { uint32_t d, depth; };
 566    union { uint32_t a, array_len; };
 567 };
 568
 569 struct isl_channel_layout {
 570    enum isl_base_type type;
 571    uint8_t bits; /**< Size in bits */
 572 };
 573
 574 struct isl_format_layout {
 575    enum isl_format format;
 576
 577    uint16_t bpb; /**< Bits per block */
 578    uint8_t bs; /**< Block size, in bytes, rounded towards 0 */
 579    uint8_t bw; /**< Block width, in pixels */
 580    uint8_t bh; /**< Block height, in pixels */
 581    uint8_t bd; /**< Block depth, in pixels */
 582
 583    struct {
 584       struct isl_channel_layout r; /**< Red channel */
 585       struct isl_channel_layout g; /**< Green channel */
 586       struct isl_channel_layout b; /**< Blue channel */
 587       struct isl_channel_layout a; /**< Alpha channel */
 588       struct isl_channel_layout l; /**< Luminance channel */
 589       struct isl_channel_layout i; /**< Intensity channel */
 590       struct isl_channel_layout p; /**< Palette channel */
 591    } channels;
 592
 593    enum isl_colorspace colorspace;
 594    enum isl_txc txc;
 595 };
 596
 597 struct isl_tile_info {
 598    enum isl_tiling tiling;
 599    uint32_t width; /**< in bytes */
 600    uint32_t height; /**< in rows of memory */
 601    uint32_t size; /**< in bytes */
 602 };
 603
 604 /**
 605  * @brief Input to surface initialization
 606  *
 607  * @invariant width >= 1
 608  * @invariant height >= 1
 609  * @invariant depth >= 1
 610  * @invariant levels >= 1
 611  * @invariant samples >= 1
 612  * @invariant array_len >= 1
 613  *
 614  * @invariant if 1D then height == 1 and depth == 1 and samples == 1
 615  * @invariant if 2D then depth == 1
 616  * @invariant if 3D then array_len == 1 and samples == 1
 617  */
 618 struct isl_surf_init_info {
 619    enum isl_surf_dim dim;
 620    enum isl_format format;
 621
 622    uint32_t width;
 623    uint32_t height;
 624    uint32_t depth;
 625    uint32_t levels;
 626    uint32_t array_len;
 627    uint32_t samples;
 628
 629    /** Lower bound for isl_surf::alignment, in bytes. */
 630    uint32_t min_alignment;
 631
 632    /** Lower bound for isl_surf::pitch, in bytes. */
 633    uint32_t min_pitch;
 634
 635    isl_surf_usage_flags_t usage;
 636
 637    /** Flags that alter how ISL selects isl_surf::tiling.  */
 638    isl_tiling_flags_t tiling_flags;
 639 };
 640
 641 struct isl_surf {
 642    enum isl_surf_dim dim;
 643    enum isl_dim_layout dim_layout;
 644    enum isl_msaa_layout msaa_layout;
 645    enum isl_tiling tiling;
 646    enum isl_format format;
 647
 648    /**
 649     * Alignment of the upper-left sample of each subimage, in units of surface
 650     * elements.
 651     */
 652    struct isl_extent3d image_alignment_el;
 653
 654    /**
 655     * Logical extent of the surface's base level, in units of pixels.  This is
 656     * identical to the extent defined in isl_surf_init_info.
 657     */
 658    struct isl_extent4d logical_level0_px;
 659
 660    /**
 661     * Physical extent of the surface's base level, in units of pixels.
 662     *
 663     * Consider isl_dim_layout as an operator that transforms a logical surface
 664     * layout to a physical surface layout. Then
 665     *
 666     *    logical_layout := (isl_surf::dim, isl_surf::logical_level0_px)
 667     *    isl_surf::phys_level0_sa := isl_surf::dim_layout * logical_layout
 668     */
 669    struct isl_extent4d phys_level0_sa;
 670
 671    uint32_t levels;
 672    uint32_t samples;
 673
 674    /** Total size of the surface, in bytes. */
 675    uint32_t size;
 676
 677    /** Required alignment for the surface's base address. */
 678    uint32_t alignment;
 679
 680    /**
 681     * Pitch between vertically adjacent samples, in bytes.
 682     */
 683    uint32_t row_pitch;
 684
 685    /**
 686     * Pitch between physical array slices, in rows of surface elements.
 687     */
 688    uint32_t array_pitch_el_rows;
 689
 690    enum isl_array_pitch_span array_pitch_span;
 691
 692    /** Copy of isl_surf_init_info::usage. */
 693    isl_surf_usage_flags_t usage;
 694 };
 695
 696 extern const struct isl_format_layout isl_format_layouts[];
 697
 698 void
 699 isl_device_init(struct isl_device *dev,
 700                 const struct brw_device_info *info);
 701
 702 static inline const struct isl_format_layout * ATTRIBUTE_CONST
 703 isl_format_get_layout(enum isl_format fmt)
 704 {
 705    return &isl_format_layouts[fmt];
 706 }
 707
 708 bool
 709 isl_format_has_sint_channel(enum isl_format fmt) ATTRIBUTE_CONST;
 710
 711 static inline bool
 712 isl_format_is_compressed(enum isl_format fmt)
 713 {
 714    const struct isl_format_layout *fmtl = isl_format_get_layout(fmt);
 715
 716    return fmtl->txc != ISL_TXC_NONE;
 717 }
 718
 719 static inline bool
 720 isl_format_has_bc_compression(enum isl_format fmt)
 721 {
 722    switch (isl_format_get_layout(fmt)->txc) {
 723    case ISL_TXC_DXT1:
 724    case ISL_TXC_DXT3:
 725    case ISL_TXC_DXT5:
 726       return true;
 727    case ISL_TXC_NONE:
 728    case ISL_TXC_FXT1:
 729    case ISL_TXC_RGTC1:
 730    case ISL_TXC_RGTC2:
 731    case ISL_TXC_BPTC:
 732    case ISL_TXC_ETC1:
 733    case ISL_TXC_ETC2:
 734       return false;
 735    }
 736
 737    unreachable("bad texture compression mode");
 738    return false;
 739 }
 740
 741 static inline bool
 742 isl_format_is_yuv(enum isl_format fmt)
 743 {
 744    const struct isl_format_layout *fmtl = isl_format_get_layout(fmt);
 745
 746    return fmtl->colorspace == ISL_COLORSPACE_YUV;
 747 }
 748
 749 static inline bool
 750 isl_format_block_is_1x1x1(enum isl_format fmt)
 751 {
 752    const struct isl_format_layout *fmtl = isl_format_get_layout(fmt);
 753
 754    return fmtl->bw == 1 && fmtl->bh == 1 && fmtl->bd == 1;
 755 }
 756
 757 enum isl_format
 758 isl_lower_storage_image_format(const struct isl_device *dev,
 759                                enum isl_format fmt);
 760
 761 static inline bool
 762 isl_tiling_is_std_y(enum isl_tiling tiling)
 763 {
 764    return (1u << tiling) & ISL_TILING_STD_Y_MASK;
 765 }
 766
 767 bool
 768 isl_tiling_get_info(const struct isl_device *dev,
 769                     enum isl_tiling tiling,
 770                     uint32_t format_block_size,
 771                     struct isl_tile_info *info);
 772
 773 void
 774 isl_tiling_get_extent(const struct isl_device *dev,
 775                       enum isl_tiling tiling,
 776                       uint32_t format_block_size,
 777                       struct isl_extent2d *e);
 778 bool
 779 isl_surf_choose_tiling(const struct isl_device *dev,
 780                        const struct isl_surf_init_info *restrict info,
 781                        enum isl_tiling *tiling);
 782
 783 static inline bool
 784 isl_surf_usage_is_display(isl_surf_usage_flags_t usage)
 785 {
 786    return usage & ISL_SURF_USAGE_DISPLAY_BIT;
 787 }
 788
 789 static inline bool
 790 isl_surf_usage_is_depth(isl_surf_usage_flags_t usage)
 791 {
 792    return usage & ISL_SURF_USAGE_DEPTH_BIT;
 793 }
 794
 795 static inline bool
 796 isl_surf_usage_is_stencil(isl_surf_usage_flags_t usage)
 797 {
 798    return usage & ISL_SURF_USAGE_STENCIL_BIT;
 799 }
 800
 801 static inline bool
 802 isl_surf_usage_is_depth_and_stencil(isl_surf_usage_flags_t usage)
 803 {
 804    return (usage & ISL_SURF_USAGE_DEPTH_BIT) &&
 805           (usage & ISL_SURF_USAGE_STENCIL_BIT);
 806 }
 807
 808 static inline bool
 809 isl_surf_usage_is_depth_or_stencil(isl_surf_usage_flags_t usage)
 810 {
 811    return usage & (ISL_SURF_USAGE_DEPTH_BIT | ISL_SURF_USAGE_STENCIL_BIT);
 812 }
 813
 814 static inline bool
 815 isl_surf_info_is_z16(const struct isl_surf_init_info *info)
 816 {
 817    return (info->usage & ISL_SURF_USAGE_DEPTH_BIT) &&
 818           (info->format == ISL_FORMAT_R16_UNORM);
 819 }
 820
 821 static inline bool
 822 isl_surf_info_is_z32_float(const struct isl_surf_init_info *info)
 823 {
 824    return (info->usage & ISL_SURF_USAGE_DEPTH_BIT) &&
 825           (info->format == ISL_FORMAT_R32_FLOAT);
 826 }
 827
 828 static inline struct isl_extent2d
 829 isl_extent2d(uint32_t width, uint32_t height)
 830 {
 831    return (struct isl_extent2d) { .w = width, .h = height };
 832 }
 833
 834 static inline struct isl_extent3d
 835 isl_extent3d(uint32_t width, uint32_t height, uint32_t depth)
 836 {
 837    return (struct isl_extent3d) { .w = width, .h = height, .d = depth };
 838 }
 839
 840 static inline struct isl_extent4d
 841 isl_extent4d(uint32_t width, uint32_t height, uint32_t depth,
 842              uint32_t array_len)
 843 {
 844    return (struct isl_extent4d) {
 845       .w = width,
 846       .h = height,
 847       .d = depth,
 848       .a = array_len,
 849    };
 850 }
 851
 852 #define isl_surf_init(dev, surf, ...) \
 853    isl_surf_init_s((dev), (surf), \
 854                    &(struct isl_surf_init_info) {  __VA_ARGS__ });
 855
 856 bool
 857 isl_surf_init_s(const struct isl_device *dev,
 858                 struct isl_surf *surf,
 859                 const struct isl_surf_init_info *restrict info);
 860
 861 /**
 862  * Alignment of the upper-left sample of each subimage, in units of surface
 863  * elements.
 864  */
 865 static inline struct isl_extent3d
 866 isl_surf_get_image_alignment_el(const struct isl_surf *surf)
 867 {
 868    return surf->image_alignment_el;
 869 }
 870
 871 /**
 872  * Alignment of the upper-left sample of each subimage, in units of surface
 873  * samples.
 874  */
 875 static inline struct isl_extent3d
 876 isl_surf_get_image_alignment_sa(const struct isl_surf *surf)
 877 {
 878    const struct isl_format_layout *fmtl = isl_format_get_layout(surf->format);
 879
 880    return (struct isl_extent3d) {
 881       .w = fmtl->bw * surf->image_alignment_el.w,
 882       .h = fmtl->bh * surf->image_alignment_el.h,
 883       .d = fmtl->bd * surf->image_alignment_el.d,
 884    };
 885 }
 886
 887 /**
 888  * Pitch between physical array slices, in rows of surface elements.
 889  */
 890 static inline uint32_t
 891 isl_surf_get_array_pitch_el_rows(const struct isl_surf *surf)
 892 {
 893    return surf->array_pitch_el_rows;
 894 }
 895
 896 /**
 897  * Pitch between physical array slices, in rows of surface samples.
 898  */
 899 static inline uint32_t
 900 isl_surf_get_array_pitch_sa_rows(const struct isl_surf *surf)
 901 {
 902    const struct isl_format_layout *fmtl = isl_format_get_layout(surf->format);
 903    return fmtl->bh * isl_surf_get_array_pitch_el_rows(surf);
 904 }
 905
 906 /**
 907  * Pitch between physical array slices, in bytes.
 908  */
 909 static inline uint32_t
 910 isl_surf_get_array_pitch(const struct isl_surf *surf)
 911 {
 912    return isl_surf_get_array_pitch_sa_rows(surf) * surf->row_pitch;
 913 }
 914
 915 #ifdef __cplusplus
 916 }
 917 #endif