Surface.java revision 66b8ec99c5fc505877b3711a52e284bbb451f836 
1/*
2 * Copyright (C) 2007 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.*;
20import android.os.Parcelable;
21import android.os.Parcel;
22import android.util.Log;
23
24/**
25 * Handle on to a raw buffer that is being managed by the screen compositor.
26 */
27public class Surface implements Parcelable {
28    private static final String LOG_TAG = "Surface";
29
30    /* flags used in constructor (keep in sync with ISurfaceComposer.h) */
31
32    /** Surface is created hidden */
33    public static final int HIDDEN              = 0x00000004;
34
35    /** The surface is to be used by hardware accelerators or DMA engines */
36    public static final int HARDWARE            = 0x00000010;
37
38    /** Implies "HARDWARE", the surface is to be used by the GPU
39     * additionally the backbuffer is never preserved for these
40     * surfaces. */
41    public static final int GPU                 = 0x00000028;
42
43    /** The surface contains secure content, special measures will
44     * be taken to disallow the surface's content to be copied from
45     * another process. In particular, screenshots and VNC servers will
46     * be disabled, but other measures can take place, for instance the
47     * surface might not be hardware accelerated. */
48    public static final int SECURE              = 0x00000080;
49
50    /** Creates a surface where color components are interpreted as
51     *  "non pre-multiplied" by their alpha channel. Of course this flag is
52     *  meaningless for surfaces without an alpha channel. By default
53     *  surfaces are pre-multiplied, which means that each color component is
54     *  already multiplied by its alpha value. In this case the blending
55     *  equation used is:
56     *
57     *    DEST = SRC + DEST * (1-SRC_ALPHA)
58     *
59     *  By contrast, non pre-multiplied surfaces use the following equation:
60     *
61     *    DEST = SRC * SRC_ALPHA * DEST * (1-SRC_ALPHA)
62     *
63     *  pre-multiplied surfaces must always be used if transparent pixels are
64     *  composited on top of each-other into the surface. A pre-multiplied
65     *  surface can never lower the value of the alpha component of a given
66     *  pixel.
67     *
68     *  In some rare situations, a non pre-multiplied surface is preferable.
69     *
70     */
71    public static final int NON_PREMULTIPLIED   = 0x00000100;
72
73    /**
74     * Creates a surface without a rendering buffer. Instead, the content
75     * of the surface must be pushed by an external entity. This is type
76     * of surface can be used for efficient camera preview or movie
77     * play back.
78     */
79    public static final int PUSH_BUFFERS        = 0x00000200;
80
81    /** Creates a normal surface. This is the default */
82    public static final int FX_SURFACE_NORMAL   = 0x00000000;
83
84    /** Creates a Blur surface. Everything behind this surface is blurred
85     * by some amount. The quality and refresh speed of the blur effect
86     * is not settable or guaranteed.
87     * It is an error to lock a Blur surface, since it doesn't have
88     * a backing store.
89     */
90    public static final int FX_SURFACE_BLUR     = 0x00010000;
91
92    /** Creates a Dim surface. Everything behind this surface is dimmed
93     * by the amount specified in setAlpha().
94     * It is an error to lock a Dim surface, since it doesn't have
95     * a backing store.
96     */
97    public static final int FX_SURFACE_DIM     = 0x00020000;
98
99    /** Mask used for FX values above */
100    public static final int FX_SURFACE_MASK     = 0x000F0000;
101
102    /* flags used with setFlags() (keep in sync with ISurfaceComposer.h) */
103
104    /** Hide the surface. Equivalent to calling hide() */
105    public static final int SURFACE_HIDDEN    = 0x01;
106
107    /** Freeze the surface. Equivalent to calling freeze() */
108    public static final int SURACE_FROZEN     = 0x02;
109
110    /** Enable dithering when compositing this surface */
111    public static final int SURFACE_DITHER    = 0x04;
112
113    public static final int SURFACE_BLUR_FREEZE= 0x10;
114
115    /* orientations for setOrientation() */
116    public static final int ROTATION_0       = 0;
117    public static final int ROTATION_90      = 1;
118    public static final int ROTATION_180     = 2;
119    public static final int ROTATION_270     = 3;
120
121    /**
122     * Disable the orientation animation
123     * {@hide}
124     */
125    public static final int FLAGS_ORIENTATION_ANIMATION_DISABLE = 0x000000001;
126
127    @SuppressWarnings("unused")
128    private int mSurface;
129    @SuppressWarnings("unused")
130    private int mSaveCount;
131    @SuppressWarnings("unused")
132    private Canvas mCanvas;
133
134    /**
135     * Exception thrown when a surface couldn't be created or resized
136     */
137    public static class OutOfResourcesException extends Exception {
138        public OutOfResourcesException() {
139        }
140        public OutOfResourcesException(String name) {
141            super(name);
142        }
143    }
144
145    /*
146     * We use a class initializer to allow the native code to cache some
147     * field offsets.
148     */
149    native private static void nativeClassInit();
150    static { nativeClassInit(); }
151
152
153    /**
154     * create a surface
155     * {@hide}
156     */
157    public Surface(SurfaceSession s,
158            int pid, int display, int w, int h, int format, int flags)
159        throws OutOfResourcesException {
160        mCanvas = new Canvas();
161        init(s,pid,display,w,h,format,flags);
162    }
163
164    /**
165     * Create an empty surface, which will later be filled in by
166     * readFromParcel().
167     * {@hide}
168     */
169    public Surface() {
170        mCanvas = new Canvas();
171    }
172
173    /**
174     * Copy another surface to this one.  This surface now holds a reference
175     * to the same data as the original surface, and is -not- the owner.
176     * {@hide}
177     */
178    public native   void copyFrom(Surface o);
179
180    /**
181     * Does this object hold a valid surface?  Returns true if it holds
182     * a physical surface, so lockCanvas() will succeed.  Otherwise
183     * returns false.
184     */
185    public native   boolean isValid();
186
187    /** Call this free the surface up. {@hide} */
188    public native   void clear();
189
190    /** draw into a surface */
191    public Canvas lockCanvas(Rect dirty) throws OutOfResourcesException {
192        /* the dirty rectangle may be expanded to the surface's size, if
193         * for instance it has been resized or if the bits were lost, since
194         * the last call.
195         */
196        return lockCanvasNative(dirty);
197    }
198
199    private native Canvas lockCanvasNative(Rect dirty);
200
201    /** unlock the surface and asks a page flip */
202    public native   void unlockCanvasAndPost(Canvas canvas);
203
204    /**
205     * unlock the surface. the screen won't be updated until
206     * post() or postAll() is called
207     */
208    public native   void unlockCanvas(Canvas canvas);
209
210    /** start/end a transaction {@hide} */
211    public static native   void openTransaction();
212    /** {@hide} */
213    public static native   void closeTransaction();
214
215    /**
216     * Freezes the specified display, No updating of the screen will occur
217     * until unfreezeDisplay() is called. Everything else works as usual though,
218     * in particular transactions.
219     * @param display
220     * {@hide}
221     */
222    public static native   void freezeDisplay(int display);
223
224    /**
225     * resume updating the specified display.
226     * @param display
227     * {@hide}
228     */
229    public static native   void unfreezeDisplay(int display);
230
231    /**
232     * set the orientation of the given display.
233     * @param display
234     * @param orientation
235     * @param flags
236     * {@hide}
237     */
238    public static native   void setOrientation(int display, int orientation, int flags);
239
240    /**
241     * set the orientation of the given display.
242     * @param display
243     * @param orientation
244     */
245    public static void setOrientation(int display, int orientation) {
246        setOrientation(display, orientation, 0);
247    }
248
249    /**
250     * set surface parameters.
251     * needs to be inside open/closeTransaction block
252     */
253    public native   void setLayer(int zorder);
254    public native   void setPosition(int x, int y);
255    public native   void setSize(int w, int h);
256
257    public native   void hide();
258    public native   void show();
259    public native   void setTransparentRegionHint(Region region);
260    public native   void setAlpha(float alpha);
261    public native   void setMatrix(float dsdx, float dtdx,
262                                   float dsdy, float dtdy);
263
264    public native   void freeze();
265    public native   void unfreeze();
266
267    public native   void setFreezeTint(int tint);
268
269    public native   void setFlags(int flags, int mask);
270
271    @Override
272    public String toString() {
273        return "Surface(native-token=" + mSurface + ")";
274    }
275
276    private Surface(Parcel source) throws OutOfResourcesException {
277        init(source);
278    }
279
280    public int describeContents() {
281        return 0;
282    }
283
284    public native   void readFromParcel(Parcel source);
285    public native   void writeToParcel(Parcel dest, int flags);
286
287    public static final Parcelable.Creator<Surface> CREATOR
288            = new Parcelable.Creator<Surface>()
289    {
290        public Surface createFromParcel(Parcel source) {
291            try {
292                return new Surface(source);
293            } catch (Exception e) {
294                Log.e(LOG_TAG, "Exception creating surface from parcel", e);
295            }
296            return null;
297        }
298
299        public Surface[] newArray(int size) {
300            return new Surface[size];
301        }
302    };
303
304    /* no user serviceable parts here ... */
305    @Override
306    protected void finalize() throws Throwable {
307        clear();
308    }
309
310    private native void init(SurfaceSession s,
311            int pid, int display, int w, int h, int format, int flags)
312            throws OutOfResourcesException;
313
314    private native void init(Parcel source);
315}
316