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(:c: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.. c:autoenum:: isl_aux_usage 47 :file: src/intel/isl/isl.h 48 :members: 49 50.. c:autofunction:: isl_aux_usage_has_fast_clears 51 52.. c:autofunction:: isl_aux_usage_has_compression 53 54.. c:autofunction:: isl_aux_usage_has_hiz 55 56.. c:autofunction:: isl_aux_usage_has_mcs 57 58.. c:autofunction:: isl_aux_usage_has_ccs 59 60Creating auxiliary surfaces 61--------------------------- 62 63Each type of data compression requires some type of auxiliary data on the side. 64For most, this involves a second auxiliary surface. ISL provides helpers for 65creating each of these types of surfaces: 66 67.. c:autofunction:: isl_surf_get_hiz_surf 68 69.. c:autofunction:: isl_surf_get_mcs_surf 70 71.. c:autofunction:: isl_surf_supports_ccs 72 73.. c:autofunction:: isl_surf_get_ccs_surf 74 75Compression state tracking 76-------------------------- 77 78All of the Intel auxiliary surface compression schemes share a common concept 79of a main surface which may or may not contain correct up-to-date data and some 80auxiliary data which says how to interpret it. The main surface is divided 81into blocks of some fixed size and some smaller block in the auxiliary data 82controls how that main surface block is to be interpreted. We then have to do 83resolves depending on the different HW units which need to interact with a 84given surface. 85 86To help drivers keep track of what all is going on and when resolves need to be 87inserted, ISL provides a finite state machine which tracks the current state of 88the main surface and auxiliary data and their relationship to each other. The 89states are encoded with the :c:enum:`isl_aux_state` enum. ISL also provides 90helper functions for operating the state machine and determining what aux op 91(if any) is required to get to the right state for a given operation. 92 93.. c:autoenum:: isl_aux_state 94 95.. c:autofunction:: isl_aux_state_has_valid_primary 96 97.. c:autofunction:: isl_aux_state_has_valid_aux 98 99.. c:autoenum:: isl_aux_op 100 101.. c:autofunction:: isl_aux_prepare_access 102 103.. c:autofunction:: isl_aux_state_transition_aux_op 104 105.. c:autofunction:: isl_aux_state_transition_write 106