1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.view;
18
19import android.graphics.Bitmap;
20import android.graphics.Canvas;
21import android.graphics.Matrix;
22import android.graphics.Paint;
23import android.graphics.Rect;
24
25/**
26 * A hardware layer can be used to render graphics operations into a hardware
27 * friendly buffer. For instance, with an OpenGL backend, a hardware layer
28 * would use a Frame Buffer Object (FBO.) The hardware layer can be used as
29 * a drawing cache when a complex set of graphics operations needs to be
30 * drawn several times.
31 */
32abstract class HardwareLayer {
33    /**
34     * Indicates an unknown dimension (width or height.)
35     */
36    static final int DIMENSION_UNDEFINED = -1;
37
38    int mWidth;
39    int mHeight;
40    DisplayList mDisplayList;
41
42    boolean mOpaque;
43
44    /**
45     * Creates a new hardware layer with undefined dimensions.
46     */
47    HardwareLayer() {
48        this(DIMENSION_UNDEFINED, DIMENSION_UNDEFINED, false);
49    }
50
51    /**
52     * Creates a new hardware layer at least as large as the supplied
53     * dimensions.
54     *
55     * @param width The minimum width of the layer
56     * @param height The minimum height of the layer
57     * @param isOpaque Whether the layer should be opaque or not
58     */
59    HardwareLayer(int width, int height, boolean isOpaque) {
60        mWidth = width;
61        mHeight = height;
62        mOpaque = isOpaque;
63    }
64
65    /**
66     * Update the paint used when drawing this layer.
67     *
68     * @param paint The paint used when the layer is drawn into the destination canvas.
69     * @see View#setLayerPaint(android.graphics.Paint)
70     */
71    void setLayerPaint(Paint paint) {}
72
73    /**
74     * Returns the minimum width of the layer.
75     *
76     * @return The minimum desired width of the hardware layer
77     */
78    int getWidth() {
79        return mWidth;
80    }
81
82    /**
83     * Returns the minimum height of the layer.
84     *
85     * @return The minimum desired height of the hardware layer
86     */
87    int getHeight() {
88        return mHeight;
89    }
90
91    /**
92     * Returns the DisplayList for the layer.
93     *
94     * @return The DisplayList of the hardware layer
95     */
96    DisplayList getDisplayList() {
97        return mDisplayList;
98    }
99
100    /**
101     * Sets the DisplayList for the layer.
102     *
103     * @param displayList The new DisplayList for this layer
104     */
105    void setDisplayList(DisplayList displayList) {
106        mDisplayList = displayList;
107    }
108
109    /**
110     * Returns whether or not this layer is opaque.
111     *
112     * @return True if the layer is opaque, false otherwise
113     */
114    boolean isOpaque() {
115        return mOpaque;
116    }
117
118    /**
119     * Sets whether or not this layer should be considered opaque.
120     *
121     * @param isOpaque True if the layer is opaque, false otherwise
122     */
123    abstract void setOpaque(boolean isOpaque);
124
125    /**
126     * Indicates whether this layer can be rendered.
127     *
128     * @return True if the layer can be rendered into, false otherwise
129     */
130    abstract boolean isValid();
131
132    /**
133     * Resize the layer, if necessary, to be at least as large
134     * as the supplied dimensions.
135     *
136     * @param width The new desired minimum width for this layer
137     * @param height The new desired minimum height for this layer
138     * @return True if the resulting layer is valid, false otherwise
139     */
140    abstract boolean resize(int width, int height);
141
142    /**
143     * Returns a hardware canvas that can be used to render onto
144     * this layer.
145     *
146     * @return A hardware canvas, or null if a canvas cannot be created
147     */
148    abstract HardwareCanvas getCanvas();
149
150    /**
151     * Destroys resources without waiting for a GC.
152     */
153    abstract void destroy();
154
155    /**
156     * This must be invoked before drawing onto this layer.
157     * @param currentCanvas
158     */
159    abstract HardwareCanvas start(Canvas currentCanvas);
160
161    /**
162     * This must be invoked after drawing onto this layer.
163     * @param currentCanvas
164     */
165    abstract void end(Canvas currentCanvas);
166
167    /**
168     * Copies this layer into the specified bitmap.
169     *
170     * @param bitmap The bitmap to copy they layer into
171     *
172     * @return True if the copy was successful, false otherwise
173     */
174    abstract boolean copyInto(Bitmap bitmap);
175
176    /**
177     * Update the layer's properties. This method should be used
178     * when the underlying storage is modified by an external entity.
179     * To change the underlying storage, use the {@link #resize(int, int)}
180     * method instead.
181     *
182     * @param width The new width of this layer
183     * @param height The new height of this layer
184     * @param isOpaque Whether this layer is opaque
185     */
186    void update(int width, int height, boolean isOpaque) {
187        mWidth = width;
188        mHeight = height;
189        mOpaque = isOpaque;
190    }
191
192    /**
193     * Sets an optional transform on this layer.
194     *
195     * @param matrix The transform to apply to the layer.
196     */
197    abstract void setTransform(Matrix matrix);
198
199    /**
200     * Specifies the display list to use to refresh the layer.
201     *
202     * @param displayList The display list containing the drawing commands to
203     *                    execute in this layer
204     * @param dirtyRect The dirty region of the layer that needs to be redrawn
205     */
206    abstract void redrawLater(DisplayList displayList, Rect dirtyRect);
207
208    /**
209     * Indicates that this layer has lost its underlying storage.
210     */
211    abstract void clearStorage();
212}
213