render_pictures: add --mismatchPath flag

tools/PictureRenderer.h

Index: tools/PictureRenderer.h
diff --git a/tools/PictureRenderer.h b/tools/PictureRenderer.h
index 342df7872abb417ded8dcc2a133d17b343fee2d8..468c567b13ce1b35a5a139b5d12b467fcf45a6b8 100644
--- a/tools/PictureRenderer.h
+++ b/tools/PictureRenderer.h
@@ -84,13 +84,15 @@ public:
      * Called with each new SkPicture to render.
      *
      * @param pict The SkPicture to render.
-     * @param outputDir The output directory within which this renderer should write files,
-     *     or NULL if this renderer should not write files at all.
+     * @param writePath The output directory within which this renderer should write all images,
+     *     or NULL if this renderer should not write all images.
+     * @param mismatchPath The output directory within which this renderer should write any images
+     *     which do not match expectations, or NULL if this renderer should not write mismatches.

[rmistry, 2014/05/15 14:26:19]

I am a little confused about the difference here.
It will write all images (regardless of them matching or not matching
expectations) to writePath. It will only write images that do not match
expectations to mismatchPath.

So if both writePath and mismatchPath are specified, images that do not match
expectations will be written to both directories? To avoid this duplication what
do you think about a boolean variable called writeOnlyMismatches that will only
write images that do not match expectations to writePath. (There is probably a
usecase I am not seeing here).

[epoger, 2014/05/15 14:39:09]

It sounds to me like you understand the difference perfectly. :-)
You're right about what the behavior would be if both writePath and mismatchPath
were specified.

I am not aware of a current use case that would require such behavior, but at
the same time I'm not sure what we would gain by PREVENTING such use.

These --writePath / --mismatchPath flags are exactly the same as the ones we
provide in https://skia.googlesource.com/skia/+/master/gm/gmmain.cpp .  It seems
to me that the tools should be consistent, in general...

If you think there is a compelling reason to change both this tool and gm,
though, let me know!

Or, maybe we should continue the behavior as it is written here, and there's
more documentation I could add that would help?

[rmistry, 2014/05/15 14:47:15]

Yes tools should be consistent.
No compelling reason, it just seemed unnecessary duplication to write the same
images in two different places if a boolean would work instead. I do not think
we should investigate changing this behavior right away but instead to keep it
in mind for the future if there is ever a refactor done of the two tools.
Since I understood the difference the documentation is probably sufficient.

      * @param inputFilename The name of the input file we are rendering.
      * @param useChecksumBasedFilenames Whether to use checksum-based filenames when writing
      *     bitmap images to disk.
      */
-    virtual void init(SkPicture* pict, const SkString* outputDir,
+    virtual void init(SkPicture* pict, const SkString* writePath, const SkString* mismatchPath,
                       const SkString* inputFilename, bool useChecksumBasedFilenames);
 
     /**
@@ -116,11 +118,13 @@ public:
      * Typically "the work" is rendering an SkPicture into a bitmap, but in some subclasses
      * it is recording the source SkPicture into another SkPicture.
      *
-     * If fOutputDir has been specified, the result of the work will be written to that dir.
+     * If fWritePath has been specified, the result of the work will be written to that dir.
+     * If fMismatchPath has been specified, and the actual image result differs from its
+     * expectation, the result of the work will be written to that dir.
      *
      * @param out If non-null, the implementing subclass MAY allocate an SkBitmap, copy the
      *            output image into it, and return it here.  (Some subclasses ignore this parameter)
-     * @return bool True if rendering succeeded and, if fOutputDir had been specified, the output
+     * @return bool True if rendering succeeded and, if fWritePath had been specified, the output
      *              was successfully written to a file.
      */
     virtual bool render(SkBitmap** out = NULL) = 0;
@@ -370,7 +374,8 @@ protected:
     BBoxHierarchyType      fBBoxHierarchyType;
     DrawFilterFlags        fDrawFilters[SkDrawFilter::kTypeCount];
     SkString               fDrawFiltersConfig;
-    SkString               fOutputDir;
+    SkString               fWritePath;
+    SkString               fMismatchPath;
     SkString               fInputFilename;
     SkTileGridFactory::TileGridInfo fGridInfo; // used when fBBoxHierarchyType is TileGrid
 
@@ -447,7 +452,7 @@ private:
 
 class SimplePictureRenderer : public PictureRenderer {
 public:
-    virtual void init(SkPicture* pict, const SkString* outputDir,
+    virtual void init(SkPicture* pict, const SkString* writePath, const SkString* mismatchPath,
                       const SkString* inputFilename, bool useChecksumBasedFilenames) SK_OVERRIDE;
 
     virtual bool render(SkBitmap** out = NULL) SK_OVERRIDE;
@@ -462,12 +467,12 @@ class TiledPictureRenderer : public PictureRenderer {
 public:
     TiledPictureRenderer();
 
-    virtual void init(SkPicture* pict, const SkString* outputDir,
+    virtual void init(SkPicture* pict, const SkString* writePath, const SkString* mismatchPath,
                       const SkString* inputFilename, bool useChecksumBasedFilenames) SK_OVERRIDE;
 
     /**
      * Renders to tiles, rather than a single canvas.
-     * If fOutputDir was provided, a separate file is
+     * If fWritePath was provided, a separate file is
      * created for each tile, named "path0.png", "path1.png", etc.
      * Multithreaded mode currently does not support writing to a file.
      */
@@ -587,7 +592,7 @@ public:
 
     ~MultiCorePictureRenderer();
 
-    virtual void init(SkPicture* pict, const SkString* outputDir,
+    virtual void init(SkPicture* pict, const SkString* writePath, const SkString* mismatchPath,
                       const SkString* inputFilename, bool useChecksumBasedFilenames) SK_OVERRIDE;
 
     /**