SkDocument base for pdf, xps, etc.

include/core/SkDocument.h

+/*
+ * Copyright 2013 Google Inc.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef SkDocument_DEFINED
+#define SkDocument_DEFINED
+
+#include "SkRect.h"
+#include "SkRefCnt.h"
+
+class SkCanvas;
+class SkWStream;
+
+/**
+ *  High-level API for creating a document-based canvas. To use..
+ *
+ *  1. Create a document, specifying a stream to store the output.
+ *  2. For each "page" of content:
+ *      a. canvas = doc->beginPage(...)
+ *      b. draw_my_content(canvas);
+ *      c. doc->endPage();
+ *  3. Close the document with doc->close().
+ */
+class SkDocument : public SkRefCnt {
+public:
+    /**
+     *  Create a PDF-backed document, writing the results into a file. If there
+     *  is an error trying to create the doc, returns NULL.
+     */
+    static SkDocument* CreatePDF(const char filename[]);

[wrong vandebo, 2013/06/10 16:41:12]

Are these factory methods and you'll have additional methods for other
multi-page output formats, i.e. XPS, etc ?  It's a bit strange to how them on
the base class otherwise.

However, based on the signatures, it looks like you'd end up with two methods
per file format.  It seems that you could just make an enum with all the file
formats and make these methods generic.  i.e.

enum DocumentType {
 kPDF,
 kEMF,
 ...
}

CreateDocument(DocumentType type, const char filename[]);

+
+    /**
+     *  Create a PDF-backed document, writing the results into a stream.
+     *  there is an error trying to create the doc, returns NULL.
+     *
+     *  The document may write to the stream at anytime during its lifetime,
+     *  until either close() is called or the document is deleted. Once close()
+     *  has been called, and all of the data has been written to the stream,
+     *  if there is a Done proc provided, it will be called with the stream.
+     *  The proc can delete the stream, or whatever it needs to do.
+     */
+    static SkDocument* CreatePDF(SkWStream*, void (*Done)(SkWStream*) = NULL);

[wrong vandebo, 2013/06/10 16:41:12]

PDF has a couple of document options: disable compression, disable link
annotations.  I'm not sure if these are generic enough, but it seems like this
is the place to pipe them through.

+
+    /**
+     *  Begin a new page for the document, returning the canvas that will draw
+     *  into the page. The document owns this canvas, and it will go out of
+     *  scope when endPage() or close() is called, or the document is deleted.
+     */
+    SkCanvas* beginPage(SkScalar width, SkScalar height,
+                        const SkRect* content = NULL);

[wrong vandebo, 2013/06/10 16:41:12]

I tried using only a rect to specify the content area at the device level but it
didn't work out.  I don't recall if there was a deeper issue or if was just that
the device layer needed a transform and using a rect at the canvas layer would
work fine. 

With both interfaces, you still need another mechanism to enable drawing in the
margin area.  In Chrome this is used to add headers and footers.

+
+    /**
+     *  Call endPage() when the content for the current page has been drawn
+     *  (into the canvas returned by beginPage()). After this call the canvas
+     *  returned by beginPage() will be out-of-scope.
+     */
+    void endPage();
+
+    /**
+     *  Call close() when all pages have been drawn. This will close the file
+     *  or stream holding the document's contents. After close() the document
+     *  can no longer add new pages. Deleting the document will automatically
+     *  call close() if need be.
+     */
+    void close();

[wrong vandebo, 2013/06/10 16:41:12]

A feature that the PDF code has that's not representable here is to emit
multiple documents with different sets of drawn pages.  In Chrome the print
preview flow uses this to decrease latency; while creating a single PDF with all
<n> pages, it also creates <n> single page PDFs.  The single page PDFs are
streamed to the print preview page as they are ready.  A on SkDocument to
combine multiple SkDocuments or a method to get an SkDocument for a subset of
pages would preserve that functionality.

+
+protected:
+    SkDocument(SkWStream*, void (*)(SkWStream*));
+    virtual ~SkDocument();
+
+    virtual SkCanvas* onBeginPage(SkScalar width, SkScalar height,
+                                  const SkRect& content) = 0;
+    virtual void onEndPage() = 0;
+    virtual void onClose(SkWStream*) = 0;
+
+    enum State {
+        kBetweenPages_State,
+        kInPage_State,
+        kClosed_State
+    };
+    State getState() const { return fState; }
+
+private:
+    SkWStream* fStream;
+    void       (*fDoneProc)(SkWStream*);
+    State      fState;    
+};
+
+#endif