src/intel/isl/README

   1 Intel Surface Layout
   2
   3 Introduction
   4 ============
   5 isl is a small library that calculates the layout of Intel GPU surfaces, queries
   6 those layouts, and queries the properties of surface formats.
   7
   8
   9 Independence from User APIs
  10 ===========================
  11 isl's API is independent of any user-facing graphics API, such as OpenGL and
  12 Vulkan. This independence allows isl to be used a shared component by multiple
  13 Intel drivers.
  14
  15 Rather than mimic the user-facing APIs, the isl API attempts to reflect Intel
  16 hardware: the actual memory layout of Intel GPU surfaces and how one programs
  17 the GPU to use those surfaces. For example:
  18
  19   - The tokens of `enum isl_format` (such as `ISL_FORMAT_R8G8B8A8_UNORM`)
  20     match those of the hardware enum `SURFACE_FORMAT` rather than the OpenGL
  21     or Vulkan format tokens.  And the values of `isl_format` and
  22     `SURFACE_FORMAT` are identical.
  23
  24   - The OpenGL and Vulkan APIs contain depth and stencil formats. However the
  25     hardware enum `SURFACE_FORMAT` does not, and therefore neither does `enum
  26     isl_format`. Rather than define new pixel formats that have no hardware
  27     counterpart, isl records the intent to use a surface as a depth or stencil
  28     buffer with the usage flags `ISL_SURF_USAGE_DEPTH_BIT` and
  29     `ISL_SURF_USAGE_STENCIL_BIT`.
  30
  31   - `struct isl_surf` distinguishes between the surface's logical dimension
  32     from the user API's perspective (`enum isl_surf_dim`, which may be 1D, 2D,
  33     or 3D) and the layout of those dimensions in memory (`enum isl_dim_layout`).
  34
  35
  36 Surface Units
  37 =============
  38
  39 Intro
  40 -----
  41 ISL takes care in its equations to correctly handle conversion among surface
  42 units (such as pixels and compression blocks) and to carefully distinguish
  43 between a surface's logical layout in the client API and its physical layout
  44 in memory.
  45
  46 Symbol names often explicitly declare their unit with a suffix:
  47
  48    - px: logical pixels
  49    - sa: physical surface samples
  50    - el: physical surface elements
  51    - sa_rows: rows of physical surface samples
  52    - el_rows: rows of physical surface elements
  53
  54 Logical units are independent of hardware generation and are closely related
  55 to the user-facing API (OpenGL and Vulkan). Physical units are dependent on
  56 hardware generation and reflect the surface's layout in memory.
  57
  58 Definitions
  59 -----------
  60 - Logical Pixels (px):
  61
  62   The surface's layout from the perspective of the client API (OpenGL and
  63   Vulkan) is in units of logical pixels. Logical pixels are independent of the
  64   surface's layout in memory.
  65
  66   A surface's width and height, in units of logical pixels, is not affected by
  67   the surface's sample count. For example, consider a VkImage created with
  68   VkImageCreateInfo{width=w0, height=h0, samples=s0}. The surface's width and
  69   height at level 0 is, in units of logical pixels, w0 and h0 regardless of
  70   the value of s0.
  71
  72   For example, the logical array length of a 3D surface is always 1, even on
  73   Gen9 where the surface's memory layout is that of an array surface
  74   (ISL_DIM_LAYOUT_GEN4_2D).
  75
  76 - Physical Surface Samples (sa):
  77
  78   For a multisampled surface, this unit has the obvious meaning.
  79   A singlesampled surface, from ISL's perspective, is simply a multisampled
  80   surface whose sample count is 1.
  81
  82   For example, consider a 2D single-level non-array surface with samples=4,
  83   width_px=64, and height_px=64 (note that the suffix 'px' indicates logical
  84   pixels). If the surface's multisample layout is ISL_MSAA_LAYOUT_INTERLEAVED,
  85   then the extent of level 0 is, in units of physical surface samples,
  86   width_sa=128, height_sa=128, depth_sa=1, array_length_sa=1. If
  87   ISL_MSAA_LAYOUT_ARRAY, then width_sa=64, height_sa=64, depth_sa=1,
  88   array_length_sa=4.
  89
  90 - Physical Surface Elements (el):
  91
  92   This unit allows ISL to treat compressed and uncompressed formats
  93   identically in many calculations.
  94
  95   If the surface's pixel format is compressed, such as ETC2, then a surface
  96   element is equivalent to a compression block. If uncompressed, then
  97   a surface element is equivalent to a surface sample. As a corollary, for
  98   a given surface a surface element is at least as large as a surface sample.
  99
 100 Errata
 101 ------
 102 ISL acquired the term 'surface element' from the Broadwell PRM [1], which
 103 defines it as follows:
 104
 105    An element is defined as a pixel in uncompresed surface formats, and as
 106    a compression block in compressed surface formats. For MSFMT_DEPTH_STENCIL
 107    type multisampled surfaces, an element is a sample.
 108
 109
 110 References
 111 ==========
 112 [1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >>
 113      RENDER_SURFACE_STATE Surface Vertical Alignment (p325)