Home | History | Annotate | Download | only in view 
      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 
     17 package android.view;
     18 
     19 import android.graphics.Bitmap;
     20 import android.graphics.Canvas;
     21 import android.graphics.Matrix;
     22 import android.graphics.Paint;
     23 import 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  */
     32 abstract 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      * @see #start(android.graphics.Canvas)
    149      * @see #end(android.graphics.Canvas)
    150      */
    151     abstract HardwareCanvas getCanvas();
    152 
    153     /**
    154      * Destroys resources without waiting for a GC.
    155      */
    156     abstract void destroy();
    157 
    158     /**
    159      * This must be invoked before drawing onto this layer.
    160      *
    161      * @param currentCanvas The canvas whose rendering needs to be interrupted
    162      */
    163     abstract HardwareCanvas start(Canvas currentCanvas);
    164 
    165     /**
    166      * This must be invoked before drawing onto this layer.
    167      *
    168      * @param dirty The dirty area to repaint
    169      * @param currentCanvas The canvas whose rendering needs to be interrupted
    170      */
    171     abstract HardwareCanvas start(Canvas currentCanvas, Rect dirty);
    172 
    173     /**
    174      * This must be invoked after drawing onto this layer.
    175      *
    176      * @param currentCanvas The canvas whose rendering needs to be resumed
    177      */
    178     abstract void end(Canvas currentCanvas);
    179 
    180     /**
    181      * Copies this layer into the specified bitmap.
    182      *
    183      * @param bitmap The bitmap to copy they layer into
    184      *
    185      * @return True if the copy was successful, false otherwise
    186      */
    187     abstract boolean copyInto(Bitmap bitmap);
    188 
    189     /**
    190      * Update the layer's properties. This method should be used
    191      * when the underlying storage is modified by an external entity.
    192      * To change the underlying storage, use the {@link #resize(int, int)}
    193      * method instead.
    194      *
    195      * @param width The new width of this layer
    196      * @param height The new height of this layer
    197      * @param isOpaque Whether this layer is opaque
    198      */
    199     void update(int width, int height, boolean isOpaque) {
    200         mWidth = width;
    201         mHeight = height;
    202         mOpaque = isOpaque;
    203     }
    204 
    205     /**
    206      * Sets an optional transform on this layer.
    207      *
    208      * @param matrix The transform to apply to the layer.
    209      */
    210     abstract void setTransform(Matrix matrix);
    211 
    212     /**
    213      * Specifies the display list to use to refresh the layer.
    214      *
    215      * @param displayList The display list containing the drawing commands to
    216      *                    execute in this layer
    217      * @param dirtyRect The dirty region of the layer that needs to be redrawn
    218      */
    219     abstract void redrawLater(DisplayList displayList, Rect dirtyRect);
    220 
    221     /**
    222      * Indicates that this layer has lost its underlying storage.
    223      */
    224     abstract void clearStorage();
    225 }
    226