[gtk/wip/chergert/glproto] next: add some comments on batch linked lists

[Christian Hergert <chergert src gnome org>]

commit c04166bc62e0f8af4fb6fb8c6ae8c3d0906ca9b8
Author: Christian Hergert <chergert redhat com>
Date:   Tue Feb 23 11:41:19 2021 -0800

    next: add some comments on batch linked lists
    
    We use 16-bit integers into the array as linked list pointers since we
    cannot use real pointers (and that'd quadruple the memory overhead anyway)

 gsk/next/gskglcommandqueue.c | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
---
diff --git a/gsk/next/gskglcommandqueue.c b/gsk/next/gskglcommandqueue.c
index bda3f9da89..eb36276f3d 100644
--- a/gsk/next/gskglcommandqueue.c
+++ b/gsk/next/gskglcommandqueue.c
@@ -461,6 +461,19 @@ begin_next_batch (GskGLCommandQueue *self)
 
   g_assert (GSK_IS_GL_COMMAND_QUEUE (self));
 
+  /* GskGLCommandBatch contains an embedded linked list using integers into the
+   * self->batches array. We can't use pointer because the batches could be
+   * realloc()'d at runtime.
+   *
+   * Before we execute the command queue, we sort the batches by framebuffer but
+   * leave the batches in place as we can just tweak the links via prev/next.
+   *
+   * Generally we only traverse forwards, so we could ignore the previous field.
+   * But to optimize the reordering of batches by framebuffer we walk backwards
+   * so we sort by most-recently-seen framebuffer to ensure draws happen in the
+   * proper order.
+   */
+
   batch = gsk_gl_command_batches_append (&self->batches);
   batch->any.next_batch_index = -1;
   batch->any.prev_batch_index = self->tail_batch_index;
@@ -927,9 +940,12 @@ gsk_gl_command_queue_sort_batches (GskGLCommandQueue *self)
   for (int i = 0; i <= self->fbo_max; i++)
     seen[i] = -1;
 
-  /* Walk in reverse, and if we've seen that framebuffer before,
-   * we want to delay this operation until right before the last
-   * batch we saw for that framebuffer.
+  /* Walk in reverse, and if we've seen that framebuffer before, we want to
+   * delay this operation until right before the last batch we saw for that
+   * framebuffer.
+   *
+   * We can do this because we don't use a framebuffer's texture until it has
+   * been completely drawn.
    */
   index = self->tail_batch_index;