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.Rect;
23
24/**
25 * A hardware layer can be used to render graphics operations into a hardware
26 * friendly buffer. For instance, with an OpenGL backend, a hardware layer
27 * would use a Frame Buffer Object (FBO.) The hardware layer can be used as
28 * a drawing cache when a complex set of graphics operations needs to be
29 * drawn several times.
30 */
31abstract class HardwareLayer {
32    /**
33     * Indicates an unknown dimension (width or height.)
34     */
35    static final int DIMENSION_UNDEFINED = -1;
36
37    int mWidth;
38    int mHeight;
39    DisplayList mDisplayList;
40
41    boolean mOpaque;
42
43    /**
44     * Creates a new hardware layer with undefined dimensions.
45     */
46    HardwareLayer() {
47        this(DIMENSION_UNDEFINED, DIMENSION_UNDEFINED, false);
48    }
49
50    /**
51     * Creates a new hardware layer at least as large as the supplied
52     * dimensions.
53     *
54     * @param width The minimum width of the layer
55     * @param height The minimum height of the layer
56     * @param isOpaque Whether the layer should be opaque or not
57     */
58    HardwareLayer(int width, int height, boolean isOpaque) {
59        mWidth = width;
60        mHeight = height;
61        mOpaque = isOpaque;
62    }
63
64    /**
65     * Returns the minimum width of the layer.
66     *
67     * @return The minimum desired width of the hardware layer
68     */
69    int getWidth() {
70        return mWidth;
71    }
72
73    /**
74     * Returns the minimum height of the layer.
75     *
76     * @return The minimum desired height of the hardware layer
77     */
78    int getHeight() {
79        return mHeight;
80    }
81
82    /**
83     * Returns the DisplayList for the layer.
84     *
85     * @return The DisplayList of the hardware layer
86     */
87    DisplayList getDisplayList() {
88        return mDisplayList;
89    }
90
91    /**
92     * Sets the DisplayList for the layer.
93     *
94     * @param displayList The new DisplayList for this layer
95     */
96    void setDisplayList(DisplayList displayList) {
97        mDisplayList = displayList;
98    }
99
100    /**
101     * Returns whether or not this layer is opaque.
102     *
103     * @return True if the layer is opaque, false otherwise
104     */
105    boolean isOpaque() {
106        return mOpaque;
107    }
108
109    /**
110     * Indicates whether this layer can be rendered.
111     *
112     * @return True if the layer can be rendered into, false otherwise
113     */
114    abstract boolean isValid();
115
116    /**
117     * Resize the layer, if necessary, to be at least as large
118     * as the supplied dimensions.
119     *
120     * @param width The new desired minimum width for this layer
121     * @param height The new desired minimum height for this layer
122     */
123    abstract void resize(int width, int height);
124
125    /**
126     * Returns a hardware canvas that can be used to render onto
127     * this layer.
128     *
129     * @return A hardware canvas, or null if a canvas cannot be created
130     */
131    abstract HardwareCanvas getCanvas();
132
133    /**
134     * Destroys resources without waiting for a GC.
135     */
136    abstract void destroy();
137
138    /**
139     * Flush the render queue associated with this layer.
140     */
141    abstract void flush();
142
143    /**
144     * This must be invoked before drawing onto this layer.
145     * @param currentCanvas
146     */
147    abstract HardwareCanvas start(Canvas currentCanvas);
148
149    /**
150     * This must be invoked after drawing onto this layer.
151     * @param currentCanvas
152     */
153    abstract void end(Canvas currentCanvas);
154
155    /**
156     * Copies this layer into the specified bitmap.
157     *
158     * @param bitmap The bitmap to copy they layer into
159     *
160     * @return True if the copy was successful, false otherwise
161     */
162    abstract boolean copyInto(Bitmap bitmap);
163
164    /**
165     * Update the layer's properties. This method should be used
166     * when the underlying storage is modified by an external entity.
167     * To change the underlying storage, use the {@link #resize(int, int)}
168     * method instead.
169     *
170     * @param width The new width of this layer
171     * @param height The new height of this layer
172     * @param isOpaque Whether this layer is opaque
173     */
174    void update(int width, int height, boolean isOpaque) {
175        mWidth = width;
176        mHeight = height;
177        mOpaque = isOpaque;
178    }
179
180    /**
181     * Sets an optional transform on this layer.
182     *
183     * @param matrix The transform to apply to the layer.
184     */
185    abstract void setTransform(Matrix matrix);
186
187    /**
188     * Specifies the display list to use to refresh the layer.
189     *
190     * @param displayList The display list containing the drawing commands to
191     *                    execute in this layer
192     * @param dirtyRect The dirty region of the layer that needs to be redrawn
193     */
194    abstract void redraw(DisplayList displayList, Rect dirtyRect);
195}
196