SkDocument.h revision 8c92dc1dc281649f9e6b0ff534c25bc89dded3ea 
1/*
2 * Copyright 2013 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkDocument_DEFINED
9#define SkDocument_DEFINED
10
11#include "SkBitmap.h"
12#include "SkPicture.h"
13#include "SkRect.h"
14#include "SkRefCnt.h"
15
16class SkCanvas;
17class SkWStream;
18
19/** SK_ScalarDefaultDPI is 72 DPI.
20*/
21#define SK_ScalarDefaultRasterDPI           72.0f
22
23/**
24 *  High-level API for creating a document-based canvas. To use..
25 *
26 *  1. Create a document, specifying a stream to store the output.
27 *  2. For each "page" of content:
28 *      a. canvas = doc->beginPage(...)
29 *      b. draw_my_content(canvas);
30 *      c. doc->endPage();
31 *  3. Close the document with doc->close().
32 */
33class SK_API SkDocument : public SkRefCnt {
34public:
35    SK_DECLARE_INST_COUNT(SkDocument)
36
37    /**
38     *  Create a PDF-backed document, writing the results into a SkWStream.
39     *
40     *  PDF pages are sized in point units. 1 pt == 1/72 inch == 127/360 mm.
41     *
42     *  @param SkWStream* A PDF document will be written to this
43     *         stream.  The document may write to the stream at
44     *         anytime during its lifetime, until either close() is
45     *         called or the document is deleted.
46     *  @param dpi The DPI (pixels-per-inch) at which features without
47     *         native PDF support will be rasterized (e.g. draw image
48     *         with perspective, draw text with perspective, ...)  A
49     *         larger DPI would create a PDF that reflects the
50     *         original intent with better fidelity, but it can make
51     *         for larger PDF files too, which would use more memory
52     *         while rendering, and it would be slower to be processed
53     *         or sent online or to printer.
54     *  @returns NULL if there is an error, otherwise a newly created
55     *           PDF-backed SkDocument.
56     */
57    static SkDocument* CreatePDF(SkWStream*,
58                                 SkScalar dpi = SK_ScalarDefaultRasterDPI);
59
60    /**
61     *  Create a PDF-backed document, writing the results into a file.
62     */
63    static SkDocument* CreatePDF(const char outputFilePath[],
64                                 SkScalar dpi = SK_ScalarDefaultRasterDPI);
65
66    /**
67     *  Begin a new page for the document, returning the canvas that will draw
68     *  into the page. The document owns this canvas, and it will go out of
69     *  scope when endPage() or close() is called, or the document is deleted.
70     */
71    SkCanvas* beginPage(SkScalar width, SkScalar height,
72                        const SkRect* content = NULL);
73
74    /**
75     *  Call endPage() when the content for the current page has been drawn
76     *  (into the canvas returned by beginPage()). After this call the canvas
77     *  returned by beginPage() will be out-of-scope.
78     */
79    void endPage();
80
81    /**
82     *  Call close() when all pages have been drawn. This will close the file
83     *  or stream holding the document's contents. After close() the document
84     *  can no longer add new pages. Deleting the document will automatically
85     *  call close() if need be.
86     *  Returns true on success or false on failure.
87     */
88    bool close();
89
90    /**
91     *  Call abort() to stop producing the document immediately.
92     *  The stream output must be ignored, and should not be trusted.
93     */
94    void abort();
95
96protected:
97    SkDocument(SkWStream*, void (*)(SkWStream*, bool aborted));
98
99    // note: subclasses must call close() in their destructor, as the base class
100    // cannot do this for them.
101    virtual ~SkDocument();
102
103    virtual SkCanvas* onBeginPage(SkScalar width, SkScalar height,
104                                  const SkRect& content) = 0;
105    virtual void onEndPage() = 0;
106    virtual bool onClose(SkWStream*) = 0;
107    virtual void onAbort() = 0;
108
109    // Allows subclasses to write to the stream as pages are written.
110    SkWStream* getStream() { return fStream; }
111
112    enum State {
113        kBetweenPages_State,
114        kInPage_State,
115        kClosed_State
116    };
117    State getState() const { return fState; }
118
119private:
120    SkWStream* fStream;
121    void       (*fDoneProc)(SkWStream*, bool aborted);
122    State      fState;
123
124    typedef SkRefCnt INHERITED;
125};
126
127#endif
128