ilo: better readability and doc for texture flags

Improve comments for the flags, and explicitly separate their uses in slice
flags and resolve flags.

3 files changed, 58 insertions, 36 deletions

diff --git a/src/gallium/drivers/ilo/ilo_blit.c b/src/gallium/drivers/ilo/ilo_blit.c
index ab1ec5bbd61..74bb3554235 100644
--- a/src/gallium/drivers/ilo/ilo_blit.c
+++ b/src/gallium/drivers/ilo/ilo_blit.c
@@ -143,7 +143,7 @@ void
 ilo_blit_resolve_slices_for_hiz(struct ilo_context *ilo,
                                 struct pipe_resource *res, unsigned level,
                                 unsigned first_slice, unsigned num_slices,
-                                unsigned flags)
+                                unsigned resolve_flags)
 {
    struct ilo_texture *tex = ilo_texture(res);
    const unsigned any_reader =
@@ -158,15 +158,15 @@ ilo_blit_resolve_slices_for_hiz(struct ilo_context *ilo,
    assert(tex->base.target != PIPE_BUFFER &&
           ilo_texture_can_enable_hiz(tex, level, first_slice, num_slices));
 
-   if (flags & ILO_TEXTURE_RENDER_WRITE) {
+   if (resolve_flags & ILO_TEXTURE_RENDER_WRITE) {
       /*
        * When ILO_TEXTURE_RENDER_WRITE is set, there can be no reader.  We
        * need to perform a HiZ Buffer Resolve in case the resource was
        * previously written by another writer, unless this is a clear.
        */
-      assert(!(flags & (other_writers | any_reader)));
+      assert(!(resolve_flags & (other_writers | any_reader)));
 
-      if (!(flags & ILO_TEXTURE_CLEAR)) {
+      if (!(resolve_flags & ILO_TEXTURE_CLEAR)) {
          for (i = 0; i < num_slices; i++) {
             const struct ilo_texture_slice *slice =
                ilo_texture_get_slice(tex, level, first_slice + i);
@@ -178,8 +178,9 @@ ilo_blit_resolve_slices_for_hiz(struct ilo_context *ilo,
          }
       }
    }
-   else if ((flags & any_reader) ||
-         ((flags & other_writers) && !(flags & ILO_TEXTURE_CLEAR))) {
+   else if ((resolve_flags & any_reader) ||
+            ((resolve_flags & other_writers) &&
+             !(resolve_flags & ILO_TEXTURE_CLEAR))) {
       /*
        * When there is at least a reader or writer, we need to perform a
        * Depth Buffer Resolve in case the resource was previously written
diff --git a/src/gallium/drivers/ilo/ilo_blit.h b/src/gallium/drivers/ilo/ilo_blit.h
index 1e33824d4d7..1e954083983 100644
--- a/src/gallium/drivers/ilo/ilo_blit.h
+++ b/src/gallium/drivers/ilo/ilo_blit.h
@@ -39,16 +39,16 @@ void
 ilo_blit_resolve_slices_for_hiz(struct ilo_context *ilo,
                                 struct pipe_resource *res, unsigned level,
                                 unsigned first_slice, unsigned num_slices,
-                                unsigned flags);
+                                unsigned resolve_flags);
 
 static inline void
 ilo_blit_resolve_slices(struct ilo_context *ilo,
                         struct pipe_resource *res, unsigned level,
                         unsigned first_slice, unsigned num_slices,
-                        unsigned flags)
+                        unsigned resolve_flags)
 {
    struct ilo_texture *tex;
-   unsigned flag_mask;
+   unsigned slice_mask;
 
    if (res->target == PIPE_BUFFER)
       return;
@@ -63,38 +63,27 @@ ilo_blit_resolve_slices(struct ilo_context *ilo,
    if (!ilo_texture_can_enable_hiz(tex, level, first_slice, num_slices))
       return;
 
-   /*
-    * flags may be
-    *
-    *  - ILO_TEXTURE_CPU_{READ,WRITE} (transfer)
-    *  - ILO_TEXTURE_BLT_{READ,WRITE} (BLT copy or clear)
-    *  - ILO_TEXTURE_RENDER_{READ,WRITE} (sample or render)
-    *  - ILO_TEXTURE_CLEAR
-    *
-    * It is assumed there is at most one writer, and that readers read before
-    * writers write.
-    */
    if (ilo_texture_can_enable_hiz(tex, level, first_slice, num_slices)) {
       ilo_blit_resolve_slices_for_hiz(ilo, res, level,
-            first_slice, num_slices, flags);
+            first_slice, num_slices, resolve_flags);
    }
 
-   /* clear writers and clear state that are not set */
-   flag_mask =
+   slice_mask =
       ILO_TEXTURE_CPU_WRITE |
       ILO_TEXTURE_BLT_WRITE |
       ILO_TEXTURE_RENDER_WRITE;
-   if (flags & flag_mask)
-      flag_mask |= ILO_TEXTURE_CLEAR;
+   /* when there is a new writer, we may need to clear ILO_TEXTURE_CLEAR */
+   if (resolve_flags & slice_mask)
+      slice_mask |= ILO_TEXTURE_CLEAR;
 
    ilo_texture_set_slice_flags(tex, level,
-         first_slice, num_slices, flag_mask, flags);
+         first_slice, num_slices, slice_mask, resolve_flags);
 }
 
 static inline void
 ilo_blit_resolve_resource(struct ilo_context *ilo,
                           struct pipe_resource *res,
-                          unsigned flags)
+                          unsigned resolve_flags)
 {
    unsigned lv;
 
@@ -102,14 +91,14 @@ ilo_blit_resolve_resource(struct ilo_context *ilo,
       const unsigned num_slices = (res->target == PIPE_TEXTURE_3D) ?
          u_minify(res->depth0, lv) : res->array_size;
 
-      ilo_blit_resolve_slices(ilo, res, lv, 0, num_slices, flags);
+      ilo_blit_resolve_slices(ilo, res, lv, 0, num_slices, resolve_flags);
    }
 }
 
 static inline void
 ilo_blit_resolve_surface(struct ilo_context *ilo,
                          struct pipe_surface *surf,
-                         unsigned flags)
+                         unsigned resolve_flags)
 {
    if (surf->texture->target == PIPE_BUFFER)
       return;
@@ -117,32 +106,32 @@ ilo_blit_resolve_surface(struct ilo_context *ilo,
    ilo_blit_resolve_slices(ilo, surf->texture,
          surf->u.tex.level, surf->u.tex.first_layer,
          surf->u.tex.last_layer - surf->u.tex.first_layer + 1,
-         flags);
+         resolve_flags);
 }
 
 static inline void
 ilo_blit_resolve_transfer(struct ilo_context *ilo,
                           const struct pipe_transfer *xfer)
 {
-   unsigned flags = 0;
+   unsigned resolve_flags = 0;
 
    if (xfer->resource->target == PIPE_BUFFER)
       return;
 
    if (xfer->usage & PIPE_TRANSFER_READ)
-      flags |= ILO_TEXTURE_CPU_READ;
+      resolve_flags |= ILO_TEXTURE_CPU_READ;
    if (xfer->usage & PIPE_TRANSFER_WRITE)
-      flags |= ILO_TEXTURE_CPU_WRITE;
+      resolve_flags |= ILO_TEXTURE_CPU_WRITE;
 
    ilo_blit_resolve_slices(ilo, xfer->resource, xfer->level,
-         xfer->box.z, xfer->box.depth, flags);
+         xfer->box.z, xfer->box.depth, resolve_flags);
 }
 
 static inline void
 ilo_blit_resolve_view(struct ilo_context *ilo,
                       const struct pipe_sampler_view *view)
 {
-   const unsigned flags = ILO_TEXTURE_RENDER_READ;
+   const unsigned resolve_flags = ILO_TEXTURE_RENDER_READ;
    unsigned lv;
 
    if (view->texture->target == PIPE_BUFFER)
@@ -161,7 +150,7 @@ ilo_blit_resolve_view(struct ilo_context *ilo,
       }
 
       ilo_blit_resolve_slices(ilo, view->texture,
-            lv, first_slice, num_slices, flags);
+            lv, first_slice, num_slices, resolve_flags);
    }
 }
 
diff --git a/src/gallium/drivers/ilo/ilo_resource.h b/src/gallium/drivers/ilo/ilo_resource.h
index fb4fde77d08..d7bc5f9be71 100644
--- a/src/gallium/drivers/ilo/ilo_resource.h
+++ b/src/gallium/drivers/ilo/ilo_resource.h
@@ -34,13 +34,45 @@
 #include "ilo_screen.h"
 
 enum ilo_texture_flags {
+   /*
+    * Possible writers of a texture.  There can be at most one writer at any
+    * time.
+    *
+    * Wine set in resolve flags (in ilo_blit_resolve_slices()), they indicate
+    * the new writer.  When set in slice flags (ilo_texture_slice::flags),
+    * they indicate the writer since last resolve.
+    */
    ILO_TEXTURE_RENDER_WRITE   = 1 << 0,
    ILO_TEXTURE_BLT_WRITE      = 1 << 1,
    ILO_TEXTURE_CPU_WRITE      = 1 << 2,
+
+   /*
+    * Possible readers of a texture.  There may be multiple readers at any
+    * time.
+    *
+    * When set in resolve flags, they indicate the new readers.  They are
+    * never set in slice flags.
+    */
    ILO_TEXTURE_RENDER_READ    = 1 << 3,
    ILO_TEXTURE_BLT_READ       = 1 << 4,
    ILO_TEXTURE_CPU_READ       = 1 << 5,
+
+   /*
+    * Set when the texture is cleared.
+    *
+    * When set in resolve flags, the new writer will clear.  When set in slice
+    * flags, the slice has been cleared.
+    */
    ILO_TEXTURE_CLEAR          = 1 << 6,
+
+   /*
+    * Set when HiZ can be enabled.
+    *
+    * It is never set in resolve flags.  When set in slice flags, the slice
+    * can have HiZ enabled.  It is to be noted that this bit is always set for
+    * either all or none of the slices in a level, allowing quick check in
+    * case of layered rendering.
+    */
    ILO_TEXTURE_HIZ            = 1 << 7,
 };