1Intel Surface Layout 2 3Introduction 4============ 5isl is a small library that calculates the layout of Intel GPU surfaces, queries 6those layouts, and queries the properties of surface formats. 7 8 9Independence from User APIs 10=========================== 11isl's API is independent of any user-facing graphics API, such as OpenGL and 12Vulkan. This independence allows isl to be used a shared component by multiple 13Intel drivers. 14 15Rather than mimic the user-facing APIs, the isl API attempts to reflect Intel 16hardware: the actual memory layout of Intel GPU surfaces and how one programs 17the 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 36Surface Units 37============= 38 39Intro 40----- 41ISL takes care in its equations to correctly handle conversion among surface 42units (such as pixels and compression blocks) and to carefully distinguish 43between a surface's logical layout in the client API and its physical layout 44in memory. 45 46Symbol 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 54Logical units are independent of hardware generation and are closely related 55to the user-facing API (OpenGL and Vulkan). Physical units are dependent on 56hardware generation and reflect the surface's layout in memory. 57 58Definitions 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 Gfx9 where the surface's memory layout is that of an array surface 74 (ISL_DIM_LAYOUT_GFX4_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 100Errata 101------ 102ISL acquired the term 'surface element' from the Broadwell PRM [1], which 103defines it as follows: 104 105 An element is defined as a pixel in uncompressed 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 110References 111========== 112[1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >> 113 RENDER_SURFACE_STATE Surface Vertical Alignment (p325) 114