# Intel Surface Layout (ISL)

The Intel Surface Layout library (ISL) is a subproject in Mesa for doing surface layout calculations for Intel graphics drivers. It was originally written by Lina Versace and is now maintained by Faith Ekstrand and Nanley Chery.

- Units
- Surface Formats
  - Data Encoding
  - Data Layout
  - Understanding sRGB
  - Surface Format Introspection API
  - Surface Format Enums
- Tiling
  - Basics
  - ISL Representation
  - X-tiling
  - Y-tiling
  - W-tiling
  - Tile4
  - Tiling as a bit pattern
- Auxiliary surface compression
  - Types of surface compression
  - Creating auxiliary surfaces
  - Compression state tracking
- Single-sampled Color Compression
  - CCS data
  - CCS surface layout
  - CCS on Tigerlake and above
- Hierarchical Depth (HiZ)
  - HiZ/stencil on Sandy Bridge

The core representation of a surface in ISL is `isl_surf`.

struct isl_surf
  enum isl_surf_dim dim

    Dimensionality of the surface

  enum isl_dim_layout dim_layout

    Spatial layout of the surface in memory

    This is dependent on `isl_surf.dim` and hardware generation.

  enum isl_msaa_layout msaa_layout

    Spatial layout of the samples if isl_surf::samples > 1

  enum isl_tiling tiling

    Memory tiling used by the surface

  enum isl_format format

    Base image format of the surface

    This need not be the same as the format specified in isl_view::format when a surface state is constructed. It must, however, have the same number of bits per pixel or else memory calculations will go wrong.

  struct isl_extent3d image_alignment_el

    Alignment of the upper-left sample of each subimage, in units of surface elements.

  struct isl_extent4d logical_level0_px

    Logical extent of the surface’s base level, in units of pixels. This is identical to the extent defined in isl_surf_init_info.

  struct isl_extent4d phys_level0_sa

    Physical extent of the surface’s base level, in units of physical surface samples.

    Consider isl_dim_layout as an operator that transforms a logical surface layout to a physical surface layout. Then

    > logical_layout := (isl_surf::dim, isl_surf::logical_level0_px) isl_surf::phys_level0_sa := isl_surf::dim_layout * logical_layout

  uint32_t levels

    Number of miplevels in the surface

  uint32_t samples

    Number of samples in the surface

    Invariant:

      samples >= 1

  uint64_t size_B

    Total size of the surface, in bytes.

  uint32_t alignment_B

    Required alignment for the surface’s base address.

  uint32_t row_pitch_B

    The interpretation of this field depends on the value of isl_tile_info::physical_extent_B. In particular, the width of the surface in tiles is row_pitch_B / isl_tile_info::physical_extent_B.width and the distance in bytes between vertically adjacent tiles in the image is given by row_pitch_B * isl_tile_info::physical_extent_B.height.

    For linear images where isl_tile_info::physical_extent_B.height == 1, this cleanly reduces to being the distance, in bytes, between vertically adjacent surface elements.

    @see isl_tile_info::phys_extent_B;

  uint32_t array_pitch_el_rows

    Pitch between physical array slices, in rows of surface elements.

  uint32_t miptail_start_level

    Level at which the miptail starts.

    This value is inclusive in the sense that the miptail contains this level.

  isl_surf_usage_flags_t usage

    Copy of isl_surf_init_info::usage.