SkPDF/Documentation: backend limitations

site/user/sample/pdf.md

 Using Skia's PDF Backend
 ========================
 
-Here is an example of using Skia's PDF backend in the recommended way:
-via the SkDocument and SkCanvas APIs.
+Here is an example of using Skia's PDF backend (SkPDF) via the
+SkDocument and SkCanvas APIs.
 
 <!--?prettify lang=cc?-->
 
     #include "SkDocument.h"
 
     bool WritePDF(SkWStream* outputStream) {
         SkDocument::PDFMetadata metadata;
         metadata.fCreator  = "creator....";
         metadata.fTitle    = "title...";
         metadata.fAuthor   = "author...";
@@ skipping 16 matching lines @@
             SkScalar pageHeight = ....;
             SkCanvas* pageCanvas =
                     pdfDocument->beginPage(pageWidth, pageHeight);
 
             // ....insert canvas draw commands here....
 
             pdfDocument->endPage();
         }
         return pdfDocument->close();
     }
+
+* * *
+
+<span id="limits">SkPDF Limitations</span>
+------------------------------------------
+
+There are several corners of Skia's public API that SkPDF does not

[djsollen, 2016/09/29 13:12:39]

SkPDF currently does not

[hal.canary, 2016/09/29 15:31:13]

Done.

+handle because either no one has asked for it or there is no simple

[djsollen, 2016/09/29 13:12:40]

replace "no one has asked for it" with "no known client uses the feature"

[hal.canary, 2016/09/29 15:31:13]

Done.

+PDF-ish way to handle it.
+
+**drop** means to draw nothing.

[djsollen, 2016/09/29 13:12:40]

put a heading above these 3 terms indicating they are a glossary of sorts.

[hal.canary, 2016/09/29 15:31:13]

Done.

+
+**ignore** mean to draw without the effect
+
+**expand** means to implement something in a non-PDF-ish way.

[djsollen, 2016/09/29 13:12:40]

does non-PDF-ish mean rasterized content instead of vector?

[hal.canary, 2016/09/29 15:31:13]

Done.

  + **expand** means to implement something in a non-PDF-ish way.
    This may mean to rasterize vector graphics, to expand paths with
    path effects into many individual paths, or to convert text to
    paths.

+
+  - *SkMaskFilter* — Mask filters are either dropped (drawText calls)

[djsollen, 2016/09/29 13:12:39]

these first 3 bullets  (and the last one) say the same thing as the table so I
wouldn't include them here.

[hal.canary, 2016/09/29 15:31:13]

Done.

+    or ignored (other draw calls).
+
+  - *SkPathEffect* — Path effects are either ignored (drawText calls)
+    or expanded (other draw calls).
+
+  - *SkColorFilter* — Color filters are either expanded (drawImage /
+    drawBitmap calls) or ignored (everything else);
+
+  - *SkImageFilter* — ImageFilter is always expanded. (Text-as-text is lost).
+
+  - *SkXferMode* — Transfer modes that are not natively supported by
+    PDF are ignored: DstOver, SrcIn, DstIn, SrcOut, DstOut, SrcATop,
+    DstATop, and Modulate.
+
+  - *SkShader* — Non-gradient shaders are expanded.
+
+<style scoped><!--
+#pdftable {border-collapse:collapse;}
+#pdftable tr th, #pdftable tr td {border:#888888 2px solid;padding: 5px;}
+--></style>
+<table id="pdftable">
+  <tr>
+    <th>Effect</th>
+    <th>text</th>
+    <th>images</th>
+    <th>everything else</th>
+  </tr>
+  <tr>
+    <th>SkMaskFilter</th>
+    <td>drop</td>
+    <td>ignore</td>
+    <td>ignore</td>
+  </tr>
+  <tr>
+    <th>SkPathEffect</th>
+    <td>ignore</td>
+    <td>n/a</td>
+    <td>expand</td>
+  </tr>
+  <tr>
+    <th>SkColorFilter</th>
+    <td>ignore</td>
+    <td>expand</td>
+    <td>ignore</td>
+  </tr>
+  <tr>
+    <th>SkImageFilter</th>
+    <td>expand</td>
+    <td>expand</td>
+    <td>expand</td>
+  </tr>
+  <tr>
+    <th>unsupported SkXferModes</th>
+    <td>ignore</td>
+    <td>ignore</td>
+    <td>ignore</td>
+  </tr>
+  <tr>
+    <th>non-gradient SkShader</th>
+    <td>expand</td>
+    <td>n/a</td>
+    <td>expand</td>
+  </tr>
+</table>
+
+Other limitations:
+
+  - *VerticalText* — drop. (No clients seem to make use of VerticalText.)
+
+  - *drawTextOnPath* — expand. (Text-as-text is lost.)
+
+  - *drawVertices* — drop.
+
+  - *drawPatch* — drop.
+
+* * *