Hierarchical Depth (HiZ) — The Mesa 3D Graphics Library latest documentation

# Hierarchical Depth (HiZ)

TODO: Add detailed docs like we have for CCS

## HiZ/stencil on Sandy Bridge

Properly enabling HiZ on Sandy Bridge requires certain special considerations. From the Sandy Bridge PRM Vol. 2, Pt. 1, 7.5.3 “Hierarchical Depth Buffer” (p. 312):

> The hierarchical depth buffer does not support the LOD field, it is assumed by hardware to be zero. A separate hierarchical depth buffer is required for each LOD used, and the corresponding buffer’s state delivered to hardware each time a new depth buffer state with modified LOD is delivered.

The `3DSTATE_STENCIL_BUFFER` packet for separate stencil (required for HiZ) on sandy bridge also lacks an LOD field. Empirically, the hardware doesn’t pull the stencil LOD from `3DSTATE_DEPTH_BUFFER`, it’s just always 0 like with HiZ.

As stated in the PRM, this means we need a separate HiZ or stencil buffer for each LOD. However, it’s not quite as simple as that. If you ignore layered rendering, things are pretty straightforward: you need one HiZ surface for each main surface slice. With layered rendering, however, we have to be a bit more clever because we need a “real” array surface at each LOD. ISL solves this with a special miptree layout for layered rendering `isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` which lays out the surface as a miptree of layered images instead of an array of miptrees. See the docs for `isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` for a nice description along with an ASCII art diagram of the layout.

Also, neither `3DSTATE_STENCIL_BUFFER` nor `3DSTATE_HIER_DEPTH_BUFFER` have their own surface dimensions or layout information on Sandy Bridge. They’re just an address and a surface pitch. Instead, all that other information is pulled from `3DSTATE_DEPTH_BUFFER`. When you combine this with the lack of LOD, this means that, technically, we have a full-sized single-LOD stencil or HiZ surface at each miplevel of which only the upper left-hand corner of each array slice ever gets used. The net effect of this is that, in `isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ`, all LODs share the same QPitch even though it’s horribly wasteful. This is actually pretty convenient for ISL because we only have the one `isl_surf.array_pitch_el_rows` field.

Due to difficulties with plumbing relocation deltas through ISL’s depth/stencil/hiz emit interface, we can’t handle this all automatically in ISL. Instead, it’s left up to the driver to do this offsetting. ISL does provide helpers for computing the offsets and they work fine with `isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` so all that’s really required is to call the ISL helper and add the computed offset to the HiZ or stencil buffer address. The following is an excerpt from BLORP where we do this as an example:

    struct blorp_address hiz_address = params->depth.aux_addr;
    #if GFX_VER == 6
    /* Sandy bridge hardware does not technically support mipmapped HiZ.
     * However, we have a special layout that allows us to make it work
     * anyway by manually offsetting to the specified miplevel.
     */
    assert(info.hiz_surf->dim_layout == ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ);
    uint32_t offset_B;
    isl_surf_get_image_offset_B_tile_sa(info.hiz_surf,
                                        info.view->base_level, 0, 0,
                                        &offset_B, NULL, NULL);
    hiz_address.offset += offset_B;
    #endif

    info.hiz_address =
       blorp_emit_reloc(batch, dw + isl_dev->ds.hiz_offset / 4,
                        hiz_address, 0);