xref: /third_party/skia/include/core/SkDocument.h (revision cb93a386) 
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 "include/core/SkRefCnt.h"
12#include "include/core/SkScalar.h"
13
14class SkCanvas;
15class SkWStream;
16struct SkRect;
17
18/** SK_ScalarDefaultDPI is 72 dots per inch. */
19static constexpr SkScalar SK_ScalarDefaultRasterDPI = 72.0f;
20
21/**
22 *  High-level API for creating a document-based canvas. To use..
23 *
24 *  1. Create a document, specifying a stream to store the output.
25 *  2. For each "page" of content:
26 *      a. canvas = doc->beginPage(...)
27 *      b. draw_my_content(canvas);
28 *      c. doc->endPage();
29 *  3. Close the document with doc->close().
30 */
31class SK_API SkDocument : public SkRefCnt {
32public:
33
34    /**
35     *  Begin a new page for the document, returning the canvas that will draw
36     *  into the page. The document owns this canvas, and it will go out of
37     *  scope when endPage() or close() is called, or the document is deleted.
38     */
39    SkCanvas* beginPage(SkScalar width, SkScalar height, const SkRect* content = nullptr);
40
41    /**
42     *  Call endPage() when the content for the current page has been drawn
43     *  (into the canvas returned by beginPage()). After this call the canvas
44     *  returned by beginPage() will be out-of-scope.
45     */
46    void endPage();
47
48    /**
49     *  Call close() when all pages have been drawn. This will close the file
50     *  or stream holding the document's contents. After close() the document
51     *  can no longer add new pages. Deleting the document will automatically
52     *  call close() if need be.
53     */
54    void close();
55
56    /**
57     *  Call abort() to stop producing the document immediately.
58     *  The stream output must be ignored, and should not be trusted.
59     */
60    void abort();
61
62protected:
63    SkDocument(SkWStream*);
64
65    // note: subclasses must call close() in their destructor, as the base class
66    // cannot do this for them.
67    ~SkDocument() override;
68
69    virtual SkCanvas* onBeginPage(SkScalar width, SkScalar height) = 0;
70    virtual void onEndPage() = 0;
71    virtual void onClose(SkWStream*) = 0;
72    virtual void onAbort() = 0;
73
74    // Allows subclasses to write to the stream as pages are written.
75    SkWStream* getStream() { return fStream; }
76
77    enum State {
78        kBetweenPages_State,
79        kInPage_State,
80        kClosed_State
81    };
82    State getState() const { return fState; }
83
84private:
85    SkWStream* fStream;
86    State      fState;
87
88    using INHERITED = SkRefCnt;
89};
90
91#endif
92