Update the documentation for GrResourceAllocator

This class has changed with reordering so we need to
freshen these up.

Bug: skia:10877
Change-Id: Ic1bfabe7b21d665e6b50cad8be4026dc3481fb9c
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/411217
Auto-Submit: Adlai Holler <adlai@google.com>
Commit-Queue: Robert Phillips <robertphillips@google.com>
Reviewed-by: Robert Phillips <robertphillips@google.com>

src/gpu/GrResourceAllocator.h

@@ -29,42 +29,51 @@ class GrDirectContext;
  * The ResourceAllocator explicitly distributes GPU resources at flush time. It operates by
  * being given the usage intervals of the various proxies. It keeps these intervals in a singly
  * linked list sorted by increasing start index. (It also maintains a hash table from proxyID
- * to interval to find proxy reuse). When it comes time to allocate the resources it
- * traverses the sorted list and:
- *     removes intervals from the active list that have completed (returning their GrSurfaces
- *     to the free pool)
-
- *     allocates a new resource (preferably from the free pool) for the new interval
- *     adds the new interval to the active list (that is sorted by increasing end index)
+ * to interval to find proxy reuse). The ResourceAllocator uses Registers (in the sense of register
+ * allocation) to represent a future surface that will be used for each proxy during
+ * `planAssignment`, and then assigns actual surfaces during `assign`.
  *
  * Note: the op indices (used in the usage intervals) come from the order of the ops in
  * their opsTasks after the opsTask DAG has been linearized.
  *
+ * The planAssignment method traverses the sorted list and:
+ *     moves intervals from the active list that have completed (returning their registers
+ *     to the free pool) into the finished list (sorted by increasing start)
+ *
+ *     allocates a new register (preferably from the free pool) for the new interval
+ *     adds the new interval to the active list (that is sorted by increasing end index)
+ *
+ * After assignment planning, the user can choose to call `makeBudgetHeadroom` which:
+ *     computes how much VRAM would be needed for new resources for all extant Registers
+ *
+ *     asks the resource cache to purge enough resources to get that much free space
+ *
+ *     if it's not possible, do nothing and return false. The user may opt to reset
+ *     the allocator and start over with a different DAG.
+ *
+ * If the user wants to commit to the current assignment plan, they call `assign` which:
+ *     instantiates lazy proxies
+ *
+ *     instantantiates new surfaces for all registers that need them
+ *
+ *     assigns the surface for each register to all the proxies that will use it
+ *
  *************************************************************************************************
  * How does instantiation failure handling work when explicitly allocating?
  *
  * In the gather usage intervals pass all the GrSurfaceProxies used in the flush should be
  * gathered (i.e., in GrOpsTask::gatherProxyIntervals).
  *
- * The allocator will churn through this list but could fail anywhere.
+ * During addInterval, read-only lazy proxies are instantiated. If that fails, the resource
+ * allocator will note the failure and ignore pretty much anything else until `reset`.
  *
- * Allocation failure handling occurs at two levels:
+ * During planAssignment, fully-lazy proxies are instantiated so that we can know their size for
+ * budgeting purposes. If this fails, return false.
  *
- * 1) If the GrSurface backing an opsTask fails to allocate then the entire opsTask is dropped.
+ * During assign, partially-lazy proxies are instantiated and new surfaces are created for all other
+ * proxies. If any of these fails, return false.
  *
- * 2) If an individual GrSurfaceProxy fails to allocate then any ops that use it are dropped
- * (via GrOpsTask::purgeOpsWithUninstantiatedProxies)
- *
- * The pass to determine which ops to drop is a bit laborious so we only check the opsTasks and
- * individual ops when something goes wrong in allocation (i.e., when the return code from
- * GrResourceAllocator::assign is bad)
- *
- * All together this means we should never attempt to draw an op which is missing some
- * required GrSurface.
- *
- * One wrinkle in this plan is that promise images are fulfilled during the gather interval pass.
- * If any of the promise images fail at this stage then the allocator is set into an error
- * state and all allocations are then scanned for failures during the main allocation pass.
+ * The drawing manager will drop the flush if any proxies fail to instantiate.
  */
 class GrResourceAllocator {
 public: