1 /*
2  * Copyright (C) 2006 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.Canvas;
20 import android.graphics.Rect;
21 
22 /**
23  * Abstract interface to someone holding a display surface.  Allows you to
24  * control the surface size and format, edit the pixels in the surface, and
25  * monitor changes to the surface.  This interface is typically available
26  * through the {@link SurfaceView} class.
27  *
28  * <p>When using this interface from a thread other than the one running
29  * its {@link SurfaceView}, you will want to carefully read the
30  * methods
31  * {@link #lockCanvas} and {@link Callback#surfaceCreated Callback.surfaceCreated()}.
32  */
33 public interface SurfaceHolder {
34 
35     /** @deprecated this is ignored, this value is set automatically when needed. */
36     @Deprecated
37     public static final int SURFACE_TYPE_NORMAL = 0;
38     /** @deprecated this is ignored, this value is set automatically when needed. */
39     @Deprecated
40     public static final int SURFACE_TYPE_HARDWARE = 1;
41     /** @deprecated this is ignored, this value is set automatically when needed. */
42     @Deprecated
43     public static final int SURFACE_TYPE_GPU = 2;
44     /** @deprecated this is ignored, this value is set automatically when needed. */
45     @Deprecated
46     public static final int SURFACE_TYPE_PUSH_BUFFERS = 3;
47 
48     /**
49      * Exception that is thrown from {@link #lockCanvas} when called on a Surface
50      * whose type is SURFACE_TYPE_PUSH_BUFFERS.
51      */
52     public static class BadSurfaceTypeException extends RuntimeException {
BadSurfaceTypeException()53         public BadSurfaceTypeException() {
54         }
55 
BadSurfaceTypeException(String name)56         public BadSurfaceTypeException(String name) {
57             super(name);
58         }
59     }
60 
61     /**
62      * A client may implement this interface to receive information about
63      * changes to the surface.  When used with a {@link SurfaceView}, the
64      * Surface being held is only available between calls to
65      * {@link #surfaceCreated(SurfaceHolder)} and
66      * {@link #surfaceDestroyed(SurfaceHolder)}.  The Callback is set with
67      * {@link SurfaceHolder#addCallback SurfaceHolder.addCallback} method.
68      */
69     public interface Callback {
70         /**
71          * This is called immediately after the surface is first created.
72          * Implementations of this should start up whatever rendering code
73          * they desire.  Note that only one thread can ever draw into
74          * a {@link Surface}, so you should not draw into the Surface here
75          * if your normal rendering will be in another thread.
76          *
77          * @param holder The SurfaceHolder whose surface is being created.
78          */
surfaceCreated(SurfaceHolder holder)79         public void surfaceCreated(SurfaceHolder holder);
80 
81         /**
82          * This is called immediately after any structural changes (format or
83          * size) have been made to the surface.  You should at this point update
84          * the imagery in the surface.  This method is always called at least
85          * once, after {@link #surfaceCreated}.
86          *
87          * @param holder The SurfaceHolder whose surface has changed.
88          * @param format The new PixelFormat of the surface.
89          * @param width The new width of the surface.
90          * @param height The new height of the surface.
91          */
surfaceChanged(SurfaceHolder holder, int format, int width, int height)92         public void surfaceChanged(SurfaceHolder holder, int format, int width,
93                 int height);
94 
95         /**
96          * This is called immediately before a surface is being destroyed. After
97          * returning from this call, you should no longer try to access this
98          * surface.  If you have a rendering thread that directly accesses
99          * the surface, you must ensure that thread is no longer touching the
100          * Surface before returning from this function.
101          *
102          * @param holder The SurfaceHolder whose surface is being destroyed.
103          */
surfaceDestroyed(SurfaceHolder holder)104         public void surfaceDestroyed(SurfaceHolder holder);
105     }
106 
107     /**
108      * Additional callbacks that can be received for {@link Callback}.
109      */
110     public interface Callback2 extends Callback {
111         /**
112          * Called when the application needs to redraw the content of its
113          * surface, after it is resized or for some other reason.  By not
114          * returning from here until the redraw is complete, you can ensure that
115          * the user will not see your surface in a bad state (at its new
116          * size before it has been correctly drawn that way).  This will
117          * typically be preceeded by a call to {@link #surfaceChanged}.
118          *
119          * As of O, {@link #surfaceRedrawNeededAsync} may be implemented
120          * to provide a non-blocking implementation. If {@link #surfaceRedrawNeededAsync}
121          * is not implemented, then this will be called instead.
122          *
123          * @param holder The SurfaceHolder whose surface has changed.
124          */
surfaceRedrawNeeded(SurfaceHolder holder)125         void surfaceRedrawNeeded(SurfaceHolder holder);
126 
127         /**
128          * An alternative to surfaceRedrawNeeded where it is not required to block
129          * until the redraw is complete. You should initiate the redraw, and return,
130          * later invoking drawingFinished when your redraw is complete.
131          *
132          * This can be useful to avoid blocking your main application thread on rendering.
133          *
134          * As of O, if this is implemented {@link #surfaceRedrawNeeded} will not be called.
135          * However it is still recommended to implement {@link #surfaceRedrawNeeded} for
136          * compatibility with older versions of the platform.
137          *
138          * @param holder The SurfaceHolder which needs redrawing.
139          * @param drawingFinished A runnable to signal completion. This may be invoked
140          * from any thread.
141          *
142          */
surfaceRedrawNeededAsync(SurfaceHolder holder, Runnable drawingFinished)143         default void surfaceRedrawNeededAsync(SurfaceHolder holder, Runnable drawingFinished) {
144             surfaceRedrawNeeded(holder);
145             drawingFinished.run();
146         }
147     }
148 
149     /**
150      * Add a Callback interface for this holder.  There can several Callback
151      * interfaces associated with a holder.
152      *
153      * @param callback The new Callback interface.
154      */
addCallback(Callback callback)155     public void addCallback(Callback callback);
156 
157     /**
158      * Removes a previously added Callback interface from this holder.
159      *
160      * @param callback The Callback interface to remove.
161      */
removeCallback(Callback callback)162     public void removeCallback(Callback callback);
163 
164     /**
165      * Use this method to find out if the surface is in the process of being
166      * created from Callback methods. This is intended to be used with
167      * {@link Callback#surfaceChanged}.
168      *
169      * @return true if the surface is in the process of being created.
170      */
isCreating()171     public boolean isCreating();
172 
173     /**
174      * Sets the surface's type.
175      *
176      * @deprecated this is ignored, this value is set automatically when needed.
177      */
178     @Deprecated
setType(int type)179     public void setType(int type);
180 
181     /**
182      * Make the surface a fixed size.  It will never change from this size.
183      * When working with a {@link SurfaceView}, this must be called from the
184      * same thread running the SurfaceView's window.
185      *
186      * @param width The surface's width.
187      * @param height The surface's height.
188      */
setFixedSize(int width, int height)189     public void setFixedSize(int width, int height);
190 
191     /**
192      * Allow the surface to resized based on layout of its container (this is
193      * the default).  When this is enabled, you should monitor
194      * {@link Callback#surfaceChanged} for changes to the size of the surface.
195      * When working with a {@link SurfaceView}, this must be called from the
196      * same thread running the SurfaceView's window.
197      */
setSizeFromLayout()198     public void setSizeFromLayout();
199 
200     /**
201      * Set the desired PixelFormat of the surface.  The default is OPAQUE.
202      * When working with a {@link SurfaceView}, this must be called from the
203      * same thread running the SurfaceView's window.
204      *
205      * @param format A constant from PixelFormat.
206      *
207      * @see android.graphics.PixelFormat
208      */
setFormat(int format)209     public void setFormat(int format);
210 
211     /**
212      * Enable or disable option to keep the screen turned on while this
213      * surface is displayed.  The default is false, allowing it to turn off.
214      * This is safe to call from any thread.
215      *
216      * @param screenOn Set to true to force the screen to stay on, false
217      * to allow it to turn off.
218      */
setKeepScreenOn(boolean screenOn)219     public void setKeepScreenOn(boolean screenOn);
220 
221     /**
222      * Start editing the pixels in the surface.  The returned Canvas can be used
223      * to draw into the surface's bitmap.  A null is returned if the surface has
224      * not been created or otherwise cannot be edited.  You will usually need
225      * to implement {@link Callback#surfaceCreated Callback.surfaceCreated}
226      * to find out when the Surface is available for use.
227      *
228      * <p>The content of the Surface is never preserved between unlockCanvas() and
229      * lockCanvas(), for this reason, every pixel within the Surface area
230      * must be written. The only exception to this rule is when a dirty
231      * rectangle is specified, in which case, non-dirty pixels will be
232      * preserved.
233      *
234      * <p>If you call this repeatedly when the Surface is not ready (before
235      * {@link Callback#surfaceCreated Callback.surfaceCreated} or after
236      * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed}), your calls
237      * will be throttled to a slow rate in order to avoid consuming CPU.
238      *
239      * <p>If null is not returned, this function internally holds a lock until
240      * the corresponding {@link #unlockCanvasAndPost} call, preventing
241      * {@link SurfaceView} from creating, destroying, or modifying the surface
242      * while it is being drawn.  This can be more convenient than accessing
243      * the Surface directly, as you do not need to do special synchronization
244      * with a drawing thread in {@link Callback#surfaceDestroyed
245      * Callback.surfaceDestroyed}.
246      *
247      * @return Canvas Use to draw into the surface.
248      */
lockCanvas()249     public Canvas lockCanvas();
250 
251 
252     /**
253      * Just like {@link #lockCanvas()} but allows specification of a dirty rectangle.
254      * Every
255      * pixel within that rectangle must be written; however pixels outside
256      * the dirty rectangle will be preserved by the next call to lockCanvas().
257      *
258      * @see android.view.SurfaceHolder#lockCanvas
259      *
260      * @param dirty Area of the Surface that will be modified.
261      * @return Canvas Use to draw into the surface.
262      */
lockCanvas(Rect dirty)263     public Canvas lockCanvas(Rect dirty);
264 
265     /**
266      * <p>Just like {@link #lockCanvas()} but the returned canvas is hardware-accelerated.
267      *
268      * <p>See the <a href="{@docRoot}guide/topics/graphics/hardware-accel.html#unsupported">
269      * unsupported drawing operations</a> for a list of what is and isn't
270      * supported in a hardware-accelerated canvas.
271      *
272      * @return Canvas Use to draw into the surface.
273      * @throws IllegalStateException If the canvas cannot be locked.
274      */
lockHardwareCanvas()275     default Canvas lockHardwareCanvas() {
276         throw new IllegalStateException("This SurfaceHolder doesn't support lockHardwareCanvas");
277     }
278 
279     /**
280      * Finish editing pixels in the surface.  After this call, the surface's
281      * current pixels will be shown on the screen, but its content is lost,
282      * in particular there is no guarantee that the content of the Surface
283      * will remain unchanged when lockCanvas() is called again.
284      *
285      * @see #lockCanvas()
286      *
287      * @param canvas The Canvas previously returned by lockCanvas().
288      */
unlockCanvasAndPost(Canvas canvas)289     public void unlockCanvasAndPost(Canvas canvas);
290 
291     /**
292      * Retrieve the current size of the surface.  Note: do not modify the
293      * returned Rect.  This is only safe to call from the thread of
294      * {@link SurfaceView}'s window, or while inside of
295      * {@link #lockCanvas()}.
296      *
297      * @return Rect The surface's dimensions.  The left and top are always 0.
298      */
getSurfaceFrame()299     public Rect getSurfaceFrame();
300 
301     /**
302      * Direct access to the surface object.  The Surface may not always be
303      * available -- for example when using a {@link SurfaceView} the holder's
304      * Surface is not created until the view has been attached to the window
305      * manager and performed a layout in order to determine the dimensions
306      * and screen position of the Surface.    You will thus usually need
307      * to implement {@link Callback#surfaceCreated Callback.surfaceCreated}
308      * to find out when the Surface is available for use.
309      *
310      * <p>Note that if you directly access the Surface from another thread,
311      * it is critical that you correctly implement
312      * {@link Callback#surfaceCreated Callback.surfaceCreated} and
313      * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed} to ensure
314      * that thread only accesses the Surface while it is valid, and that the
315      * Surface does not get destroyed while the thread is using it.
316      *
317      * <p>This method is intended to be used by frameworks which often need
318      * direct access to the Surface object (usually to pass it to native code).
319      *
320      * @return Surface The surface.
321      */
getSurface()322     public Surface getSurface();
323 }
324