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>
diff --git a/src/gpu/GrResourceAllocator.h b/src/gpu/GrResourceAllocator.h
index 348d9b4..6d7c968 100644
--- a/src/gpu/GrResourceAllocator.h
+++ b/src/gpu/GrResourceAllocator.h
@@ -29,42 +29,51 @@
* 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: