SkMultiSKP: version 2

Measurable size improvement.

BUG=skia:5370

GOLD_TRYBOT_URL= https://gold.skia.org/search?issue=2255333003

Review-Url: https://codereview.chromium.org/2255333003

1 files changed, 32 insertions, 0 deletions

diff --git a/src/utils/SkMultiPictureDocument.h b/src/utils/SkMultiPictureDocument.h
index 1da105e1b6..ac782606ff 100644
--- a/src/utils/SkMultiPictureDocument.h
+++ b/src/utils/SkMultiPictureDocument.h
@@ -7,6 +7,38 @@
 #ifndef SkMultiPictureDocument_DEFINED
 #define SkMultiPictureDocument_DEFINED
 
+/*
+  This format is not intended to be used in production.
+
+  For clients looking for a way to represent a document in memory,
+
+    struct Doc {
+        std::vector<sk_sp<SkPicture>> fPages;
+        std::vector<SkSize> fPageSizes;
+    };
+
+  or
+
+    struct Page {
+        sk_sp<SkPicture> fPage;
+        SkSize fPageSize;
+    };
+    std::vector<Page> pages;
+
+  would work much better.
+
+  Multi-SkPicture (MSKP) files are still useful for debugging and
+  testing.
+
+  The downsides of this format are currently:
+  - no way to extract a single page; must read the entire file at once.
+  - must use `dm` to convert to another format before passing into
+    standard skp tools.
+  - `dm` can extract the first page to skp, but no others.
+
+  TODO(halcanary): replace with somthing that addresses these issues.
+ */
+
 #include "SkDocument.h"
 
 /** Writes into an experimental, undocumented file format that is