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