SkDocument/PDF: new API

include/core/SkDocument.h

Index: include/core/SkDocument.h
diff --git a/include/core/SkDocument.h b/include/core/SkDocument.h
index e5d8cf3a9bab04cf52552953879b18bb42c24080..0087acc9b2191fe0efdd4fd768373a5f65c6944f 100644
--- a/include/core/SkDocument.h
+++ b/include/core/SkDocument.h
@@ -35,7 +35,74 @@ class SkWStream;
  */
 class SK_API SkDocument : public SkRefCnt {
 public:
+    struct OptionalTimestamp {
+        bool enabled;
+        SkTime::DateTime dateTime;
+        OptionalTimestamp() : enabled(false) {}
+    };
+
+    /**
+     *  Optional metadata to be passed into the PDF factory function.
+     */
+    struct PDFMetadata {
+        SkString title;

[reed1, 2016/04/25 19:14:30]

why not use skia fField convention?

[hal.canary, 2016/04/25 21:51:33]

Done.

+        SkString author;
+        SkString subject;
+        SkString keywords;
+        SkString creator;
+        OptionalTimestamp creation;
+        OptionalTimestamp modified;
+    };
+
     /**
+     *  Create a PDF-backed document, writing the results into a
+     *  SkWStream.
+     *
+     *  PDF pages are sized in point units. 1 pt == 1/72 inch ==
+     *  127/360 mm.
+     *
+     *  @param stream A PDF document will be written to this
+     *         stream.  The document may write to the stream at
+     *         anytime during its lifetime, until either close() is
+     *         called or the document is deleted.
+     *  @param dpi The DPI (pixels-per-inch) at which features without
+     *         native PDF support will be rasterized (e.g. draw image
+     *         with perspective, draw text with perspective, ...)  A
+     *         larger DPI would create a PDF that reflects the
+     *         original intent with better fidelity, but it can make
+     *         for larger PDF files too, which would use more memory
+     *         while rendering, and it would be slower to be processed
+     *         or sent online or to printer.
+     *  @param metadata a PDFmetadata object.  Any fields may be left
+     *         empty.
+     *  @param jpegEncoder For PDF documents, if a jpegEncoder is set,
+     *         use it to encode SkImages and SkBitmaps as [JFIF]JPEGs.
+     *         This feature is deprecated and is only supplied for
+     *         backwards compatability.
+     *         The prefered method to create PDFs with JPEG images is
+     *         to use SkImage::NewFromEncoded() and not jpegEncoder.
+     *         Chromium uses NewFromEncoded.
+     *         If the encoder is unset, or if jpegEncoder->onEncode()
+     *         returns NULL, fall back on encoding images losslessly
+     *         with Deflate.
+     *  @param pdfa Iff true, include XMP metadata, a document UUID,
+     *         and sRGB output intent information.  This adds length
+     *         to the document and makes it non-reproducable, but are
+     *         necessary features for PDF/A-2b conformance
+     *
+     *  @returns NULL if there is an error, otherwise a newly created
+     *           PDF-backed SkDocument.
+     */
+    static sk_sp<SkDocument> MakePDF(
+            SkWStream* stream,
+            SkScalar dpi,
+            const SkDocument::PDFMetadata& metadata,
+            SkPixelSerializer* jpegEncoder,
+            bool pdfa);
+
+    /**
+     *  DEPRECATED: use SkDocument::MakePDF instead.
+     *
      *  Create a PDF-backed document, writing the results into a SkWStream.
      *
      *  PDF pages are sized in point units. 1 pt == 1/72 inch == 127/360 mm.
@@ -59,6 +126,8 @@ public:
                                  SkScalar dpi = SK_ScalarDefaultRasterDPI);
 
     /**
+     *  DEPRECATED: use SkDocument::MakePDF instead.
+     *
      *  @param jpegEncoder For PDF documents, if a jpegEncoder is set,
      *         use it to encode SkImages and SkBitmaps as [JFIF]JPEGs.
      *         This feature is deprecated and is only supplied for
@@ -77,6 +146,8 @@ public:
                                  SkPixelSerializer* jpegEncoder);
 
     /**
+     *  DEPRECATED: use SkDocument::MakePDF instead.
+     *
      *  Create a PDF-backed document, writing the results into a file.
      */
     static SkDocument* CreatePDF(const char outputFilePath[],
@@ -126,6 +197,9 @@ public:
     void abort();
 
     /**
+     *  DEPRECATED: use SkDocument::PDFMetadata and
+     *  SkDocument::MakePDF instead.
+     *
      *  Set the document's metadata, if supported by the document
      *  type.  The creationDate and modifiedDate parameters can be
      *  nullptr.  For example: