Update the SkDocument interface to allow for 1) abort won't emit pdf, 2) close can report success/f…

include/core/SkDocument.h

Index: include/core/SkDocument.h
diff --git a/include/core/SkDocument.h b/include/core/SkDocument.h
index bbed64a80691fb3fde1358904ec02ba5b5bb8d3b..f8e805dbd8ec7b013adb617d702a45178c7e0992 100644
--- a/include/core/SkDocument.h
+++ b/include/core/SkDocument.h
@@ -10,6 +10,9 @@
 
 #include "SkRect.h"
 #include "SkRefCnt.h"
+#include "SkBitmap.h"
+#include "SkPicture.h"
+#include "SkRect.h"
 
 class SkCanvas;
 class SkWStream;
@@ -31,8 +34,11 @@ public:
     /**
      *  Create a PDF-backed document, writing the results into a file.
      *  If there is an error trying to create the doc, returns NULL.
+     *  encoder sets the DCTEncoder for images, to encode a bitmap
+     *    as JPEG (DCT).
      */
-    static SkDocument* CreatePDF(const char filename[]);
+    static SkDocument* CreatePDF(const char filename[],
+                                 SkPicture::EncodeBitmap encoder = NULL);
 
     /**
      *  Create a PDF-backed document, writing the results into a stream.
@@ -43,16 +49,24 @@ public:
      *  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.
+     *  encoder sets the DCTEncoder for images, to encode a bitmap
+     *    as JPEG (DCT).
      */
-    static SkDocument* CreatePDF(SkWStream*, void (*Done)(SkWStream*) = NULL);
+    static SkDocument* CreatePDF(SkWStream*, void (*Done)(SkWStream*) = NULL,
+                                 SkPicture::EncodeBitmap encoder = NULL);

[reed1, 2013/10/07 13:24:54]

I wonder, if we end up with more options in the future, if we want to allow
these to be set after construction. e.g. setBitmapEncoder(...), or is it vital
to keep all of them in the constructor (i.e. known a factory time)?

Not requesting a change to this CL, just wondering.

[edisonn, 2013/10/07 19:29:06]

IMHO, since this is a function pointer, the caller can dynamically change the
behavior of the function, without having to explicitly set a new encoder. But I
have no preference, either way.

On 2013/10/07 13:24:54, reed1 wrote:

 
     /**
      *  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.
+     *  @param trimSize The content size of the page in points.
+     *         Everything outside of trimBox is considered non essential,
+     *         for example margins are outside of trim box.
+     *  @param mediaBox The Page size in points. If mediaBox is null, then we
+     *         set the mediaBox to the trim rectangle.
      */
-    SkCanvas* beginPage(SkScalar width, SkScalar height,
-                        const SkRect* content = NULL);
+    SkCanvas* beginPage(const SkSize& trimSize,

[reed1, 2013/10/07 13:24:54]

I need a better (easier) picture of what these sizes/rects mean. trimSize may be
correct, but its a funny word given we're creating a page. Why isn't it
pageSize?

[edisonn, 2013/10/07 19:29:06]

A good reason would be to maintain consistency with the XPS code. Ben, care to
comment?


On 2013/10/07 13:24:54, reed1 wrote:

+                        const SkRect* mediaBox = NULL);
 
     /**
      *  Call endPage() when the content for the current page has been drawn
@@ -66,8 +80,15 @@ public:
      *  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.
+     *  Returns true on success or false on failure.
+     */
+    bool close();
+
+    /**
+     *  Call abort() to stop producing the document immediately.
+     *  The stream output must be ignored, and should not be trusted.
      */
-    void close();
+    void abort();
 
 protected:
     SkDocument(SkWStream*, void (*)(SkWStream*));
@@ -75,10 +96,11 @@ protected:
     // cannot do this for them.
     virtual ~SkDocument();
 
-    virtual SkCanvas* onBeginPage(SkScalar width, SkScalar height,
-                                  const SkRect& content) = 0;
+    virtual SkCanvas* onBeginPage(const SkSize& trimSize,
+                                  const SkRect* mediaBox) = 0;
     virtual void onEndPage() = 0;
-    virtual void onClose(SkWStream*) = 0;
+    virtual bool onClose(SkWStream*) = 0;
+    virtual void onAbort() = 0;
 
     enum State {
         kBetweenPages_State,