1Auxiliary surface compression 2============================= 3 4Most lossless image compression on Intel hardware, be that CCS, MCS, or HiZ, 5works by way of some chunk of auxiliary data (often a surface) which is used 6together with the main surface to provide compression. Even though this means 7more memory is allocated, the scheme allows us to reduce our over-all memory 8bandwidth since the auxiliary data is much smaller than the main surface. 9 10The simplest example of this is single-sample fast clears 11(:cpp:enumerator:`isl_aux_usage::ISL_AUX_USAGE_CCS_D`) on Ivy Bridge through 12Broadwell and later. For this scheme, the auxiliary surface stores a single 13bit for each cache-line-pair in the main surface. If that bit is set, then the 14entire cache line pair contains only the clear color as provided in the 15``RENDER_SURFACE_STATE`` for the image. If the bit is unset, then it's not 16clear and you should look at the main surface. Since a cache line is 64B, this 17yields a scale-down factor of 1:1024. 18 19Even the simple fast-clear scheme saves us bandwidth in two places. The first 20is when we go to clear the surface. If we're doing a full-surface clear or 21clearing to the same color that was used to clear before, we don't have to 22touch the main surface at all. All we have to do is record the clear color and 23smash the aux data to ``0xff``. The hardware then knows to ignore whatever is 24in the main surface and look at the clear color instead. The second is when we 25go to render. Say we're doing some color blending. Instead of the blend unit 26having to read back actual surface contents to blend with, it looks at the 27clear bit and blends with the clear color recorded with the surface state 28instead. Depending on the geometry and cache utilization, this can save as 29much as one whole read of the surface worth of bandwidth. 30 31The difficulty with a scheme like this comes when we want to do something else 32with that surface. What happens if the sampler doesn't support this fast-clear 33scheme (it doesn't on IVB)? In that case, we have to do a *resolve* where we 34run a special pipeline that reads the auxiliary data and applies it to the main 35surface. In the case of fast clears, this means that, for every 1 bit in the 36auxiliary surface, the corresponding pair of cache lines in the main surface 37gets filled with the clear color. At the end of the resolve operation, the 38main surface contents are the actual contents of the surface. 39 40Types of surface compression 41---------------------------- 42 43Intel hardware has several different compression schemes that all work along 44similar lines: 45 46.. doxygenenum:: isl_aux_usage 47.. doxygenfunction:: isl_aux_usage_has_fast_clears 48.. doxygenfunction:: isl_aux_usage_has_compression 49.. doxygenfunction:: isl_aux_usage_has_hiz 50.. doxygenfunction:: isl_aux_usage_has_mcs 51.. doxygenfunction:: isl_aux_usage_has_ccs 52 53Creating auxiliary surfaces 54--------------------------- 55 56Each type of data compression requires some type of auxiliary data on the side. 57For most, this involves a second auxiliary surface. ISL provides helpers for 58creating each of these types of surfaces: 59 60.. doxygenfunction:: isl_surf_get_hiz_surf 61.. doxygenfunction:: isl_surf_get_mcs_surf 62.. doxygenfunction:: isl_surf_supports_ccs 63.. doxygenfunction:: isl_surf_get_ccs_surf 64 65Compression state tracking 66-------------------------- 67 68All of the Intel auxiliary surface compression schemes share a common concept 69of a main surface which may or may not contain correct up-to-date data and some 70auxiliary data which says how to interpret it. The main surface is divided 71into blocks of some fixed size and some smaller block in the auxiliary data 72controls how that main surface block is to be interpreted. We then have to do 73resolves depending on the different HW units which need to interact with a 74given surface. 75 76To help drivers keep track of what all is going on and when resolves need to be 77inserted, ISL provides a finite state machine which tracks the current state of 78the main surface and auxiliary data and their relationship to each other. The 79states are encoded with the :cpp:enum:`isl_aux_state` enum. ISL also provides 80helper functions for operating the state machine and determining what aux op 81(if any) is required to get to the right state for a given operation. 82 83.. doxygenenum:: isl_aux_state 84.. doxygenfunction:: isl_aux_state_has_valid_primary 85.. doxygenfunction:: isl_aux_state_has_valid_aux 86.. doxygenenum:: isl_aux_op 87.. doxygenfunction:: isl_aux_prepare_access 88.. doxygenfunction:: isl_aux_state_transition_aux_op 89.. doxygenfunction:: isl_aux_state_transition_write 90