1/*
2 * Copyright 2012 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 SkImage_DEFINED
9#define SkImage_DEFINED
10
11#include "SkImageInfo.h"
12#include "SkImageEncoder.h"
13#include "SkRefCnt.h"
14#include "SkScalar.h"
15
16class SkData;
17class SkCanvas;
18class SkPaint;
19class SkShader;
20class GrContext;
21class GrTexture;
22
23// need for TileMode
24#include "SkShader.h"
25
26/**
27 *  SkImage is an abstraction for drawing a rectagle of pixels, though the
28 *  particular type of image could be actually storing its data on the GPU, or
29 *  as drawing commands (picture or PDF or otherwise), ready to be played back
30 *  into another canvas.
31 *
32 *  The content of SkImage is always immutable, though the actual storage may
33 *  change, if for example that image can be re-created via encoded data or
34 *  other means.
35 */
36class SK_API SkImage : public SkRefCnt {
37public:
38    SK_DECLARE_INST_COUNT(SkImage)
39
40    typedef SkImageInfo Info;
41
42    static SkImage* NewRasterCopy(const Info&, const void* pixels, size_t rowBytes);
43    static SkImage* NewRasterData(const Info&, SkData* pixels, size_t rowBytes);
44    static SkImage* NewEncodedData(SkData*);
45
46    /**
47     * GrTexture is a more logical parameter for this factory, but its
48     * interactions with scratch cache still has issues, so for now we take
49     * SkBitmap instead. This will be changed in the future. skbug.com/1449
50     */
51    static SkImage* NewTexture(const SkBitmap&);
52
53    int width() const { return fWidth; }
54    int height() const { return fHeight; }
55    uint32_t uniqueID() const { return fUniqueID; }
56
57    /**
58     * Return the GrTexture that stores the image pixels. Calling getTexture
59     * does not affect the reference count of the GrTexture object.
60     * Will return NULL if the image does not use a texture.
61     */
62    GrTexture* getTexture();
63
64    SkShader*   newShaderClamp() const;
65    SkShader*   newShader(SkShader::TileMode, SkShader::TileMode) const;
66
67    void draw(SkCanvas*, SkScalar x, SkScalar y, const SkPaint*);
68
69    /**
70     *  Draw the image, cropped to the src rect, to the dst rect of a canvas.
71     *  If src is larger than the bounds of the image, the rest of the image is
72     *  filled with transparent black pixels.
73     *
74     *  See SkCanvas::drawBitmapRectToRect for similar behavior.
75     */
76    void draw(SkCanvas*, const SkRect* src, const SkRect& dst, const SkPaint*);
77
78    /**
79     *  If the image has direct access to its pixels (i.e. they are in local
80     *  RAM) return the (const) address of those pixels, and if not null, return
81     *  the ImageInfo and rowBytes. The returned address is only valid while
82     *  the image object is in scope.
83     *
84     *  On failure, returns NULL and the info and rowBytes parameters are
85     *  ignored.
86     */
87    const void* peekPixels(SkImageInfo* info, size_t* rowBytes) const;
88
89    /**
90     *  Encode the image's pixels and return the result as a new SkData, which
91     *  the caller must manage (i.e. call unref() when they are done).
92     *
93     *  If the image type cannot be encoded, or the requested encoder type is
94     *  not supported, this will return NULL.
95     */
96    SkData* encode(SkImageEncoder::Type t = SkImageEncoder::kPNG_Type,
97                   int quality = 80) const;
98
99protected:
100    SkImage(int width, int height) :
101        fWidth(width),
102        fHeight(height),
103        fUniqueID(NextUniqueID()) {
104
105        SkASSERT(width >= 0);
106        SkASSERT(height >= 0);
107    }
108
109private:
110    const int       fWidth;
111    const int       fHeight;
112    const uint32_t  fUniqueID;
113
114    static uint32_t NextUniqueID();
115
116    typedef SkRefCnt INHERITED;
117
118    /**
119     *  Return a copy of the image's pixels, limiting them to the subset
120     *  rectangle's intersection wit the image bounds. If subset is NULL, then
121     *  the entire image will be considered.
122     *
123     *  If the bitmap's pixels have already been allocated, then readPixels()
124     *  will succeed only if it can support converting the image's pixels into
125     *  the bitmap's ColorType/AlphaType. Any pixels in the bitmap that do not
126     *  intersect with the image's bounds and the subset (if not null) will be
127     *  left untouched.
128     *
129     *  If the bitmap is initially empty/unallocated, then it will be allocated
130     *  using the default allocator, and the ColorType/AlphaType will be chosen
131     *  to most closely fit the image's configuration.
132     *
133     *  On failure, false will be returned, and bitmap will unmodified.
134     */
135    // On ice for now:
136    // - should it respect the particular colortype/alphatype of the src
137    // - should it have separate entrypoints for preallocated and not bitmaps?
138    // - isn't it enough to allow the caller to draw() the image into a canvas?
139    bool readPixels(SkBitmap* bitmap, const SkIRect* subset = NULL) const;
140};
141
142#endif
143