From: Chad Versace Date: Fri, 15 Jan 2016 18:00:13 +0000 (-0800) Subject: isl: Add a README X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=8ab527de03a5bb9acdf1b88378623ebfadfccf42;p=mesa.git isl: Add a README Most of the file-level comment in isl.h is moved to the README. --- diff --git a/src/isl/README b/src/isl/README new file mode 100644 index 00000000000..1ab4313fcc5 --- /dev/null +++ b/src/isl/README @@ -0,0 +1,113 @@ +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 + 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 'surface element' from the Broadwell PRM [1], which +defines it as follows: + + An element is defined as a pixel in uncompresed 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) diff --git a/src/isl/isl.h b/src/isl/isl.h index 2194818d7b7..4b3f179303d 100644 --- a/src/isl/isl.h +++ b/src/isl/isl.h @@ -26,93 +26,13 @@ * @brief Intel Surface Layout * * Header Layout - * ============= - * + * ------------- * The header is ordered as: * - forward declarations * - macros that may be overridden at compile-time for specific gens * - enums and constants * - structs and unions * - functions - * - * - * 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 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 - * MSFMT_DEPTH_STENCIL type multisampled surfaces, an element is a sample. - * - * [1]: Broadwell PRM >> Volume 2d: Command Reference: Structures >> - * RENDER_SURFACE_STATE Surface Vertical Alignment (p325) */ #pragma once