IABSD.fr/xenocara/lib/mesa/src/intel/isl/README

Branch : - branch - master - tag -

• Show log

  Commit

• Author : jsg
  Date : 2023-01-28 08:09:28
  Hash : 5642995e
  Message : Import Mesa 22.3.4

• lib/mesa/src/intel/isl/README

• Intel Surface Layout
  
  Introduction
  ============
  isl is a small library that calculates the layout of Intel GPU surfaces, queries
  those layouts, and queries the properties of surface formats.
  
  
  Independence from User APIs
  ===========================
  isl's API is independent of any user-facing graphics API, such as OpenGL and
  Vulkan. This independence allows isl to be used a shared component by multiple
  Intel drivers.
  
  Rather than mimic the user-facing APIs, the isl API attempts to reflect Intel
  hardware: the actual memory layout of Intel GPU surfaces and how one programs
  the GPU to use those surfaces. For example:
  
    - The tokens of `enum isl_format` (such as `ISL_FORMAT_R8G8B8A8_UNORM`)
      match those of the hardware enum `SURFACE_FORMAT` rather than the OpenGL
      or Vulkan format tokens.  And the values of `isl_format` and
      `SURFACE_FORMAT` are identical.
  
    - The OpenGL and Vulkan APIs contain depth and stencil formats. However the
      hardware enum `SURFACE_FORMAT` does not, and therefore neither does `enum
      isl_format`. Rather than define new pixel formats that have no hardware
      counterpart, isl records the intent to use a surface as a depth or stencil
      buffer with the usage flags `ISL_SURF_USAGE_DEPTH_BIT` and
      `ISL_SURF_USAGE_STENCIL_BIT`.
  
    - `struct isl_surf` distinguishes between the surface's logical dimension
      from the user API's perspective (`enum isl_surf_dim`, which may be 1D, 2D,
      or 3D) and the layout of those dimensions in memory (`enum isl_dim_layout`).
  
  
  Surface Units
  =============
  
  Intro
  -----
  ISL takes care in its equations to correctly handle conversion among surface
  units (such as pixels and compression blocks) and to carefully distinguish
  between a surface's logical layout in the client API and its physical layout
  in memory.
  
  Symbol names often explicitly declare their unit with a suffix:
  
     - px: logical pixels
     - sa: physical surface samples
     - el: physical surface elements
     - sa_rows: rows of physical surface samples
     - el_rows: rows of physical surface elements
  
  Logical units are independent of hardware generation and are closely related
  to the user-facing API (OpenGL and Vulkan). Physical units are dependent on
  hardware generation and reflect the surface's layout in memory.
  
  Definitions
  -----------
  - Logical Pixels (px):
  
    The surface's layout from the perspective of the client API (OpenGL and
    Vulkan) is in units of logical pixels. Logical pixels are independent of the
    surface's layout in memory.
  
    A surface's width and height, in units of logical pixels, is not affected by
    the surface's sample count. For example, consider a VkImage created with
    VkImageCreateInfo{width=w0, height=h0, samples=s0}. The surface's width and
    height at level 0 is, in units of logical pixels, w0 and h0 regardless of
    the value of s0.
  
    For example, the logical array length of a 3D surface is always 1, even on
    Gfx9 where the surface's memory layout is that of an array surface
    (ISL_DIM_LAYOUT_GFX4_2D).
  
  - Physical Surface Samples (sa):
  
    For a multisampled surface, this unit has the obvious meaning.
    A singlesampled surface, from ISL's perspective, is simply a multisampled
    surface whose sample count is 1.
  
    For example, consider a 2D single-level non-array surface with samples=4,
    width_px=64, and height_px=64 (note that the suffix 'px' indicates logical
    pixels). If the surface's multisample layout is ISL_MSAA_LAYOUT_INTERLEAVED,
    then the extent of level 0 is, in units of physical surface samples,
    width_sa=128, height_sa=128, depth_sa=1, array_length_sa=1. If
    ISL_MSAA_LAYOUT_ARRAY, then width_sa=64, height_sa=64, depth_sa=1,
    array_length_sa=4.
  
  - Physical Surface Elements (el):
  
    This unit allows ISL to treat compressed and uncompressed formats
    identically in many calculations.
  
    If the surface's pixel format is compressed, such as ETC2, then a surface
    element is equivalent to a compression block. If uncompressed, then
    a surface element is equivalent to a surface sample. As a corollary, for
    a given surface a surface element is at least as large as a surface sample.
  
  Errata
  ------
  ISL acquired the term 'surface element' from the Broadwell PRM [1], which
  defines it as follows:
  
     An element is defined as a pixel in uncompressed surface formats, and as
     a compression block in compressed surface formats. For MSFMT_DEPTH_STENCIL
     type multisampled surfaces, an element is a sample.
  
  
  References
  ==========
  [1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >>
       RENDER_SURFACE_STATE Surface Vertical Alignment (p325)