diff options
| -rw-r--r-- | src/isl/isl.h | 62 |
1 files changed, 60 insertions, 2 deletions
diff --git a/src/isl/isl.h b/src/isl/isl.h index 2f5a6ffe1c4..22435e923b9 100644 --- a/src/isl/isl.h +++ b/src/isl/isl.h @@ -39,7 +39,14 @@ * Surface Units * ============= * - * Some symbol names have a unit suffix. + * 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 @@ -47,7 +54,58 @@ * - sa_rows: rows of physical surface samples * - el_rows: rows of physical surface elements * - * The Broadwell PRM [1] defines a surface element as follows: + * 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 Gen9 where the surface's memory layout is that of an array surface + * (ISL_DIM_LAYOUT_GEN4_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 'element' from the Broadwell PRM [1], which defines + * a surface element as follows: * * An element is defined as a pixel in uncompresed surface formats, and as * a compression block in compressed surface formats. For |