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 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
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 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
110References
111==========
112[1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >>
113 RENDER_SURFACE_STATE Surface Vertical Alignment (p325)
114