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 * @param holder The SurfaceHolder whose surface has changed. 120 */ surfaceRedrawNeeded(SurfaceHolder holder)121 public void surfaceRedrawNeeded(SurfaceHolder holder); 122 } 123 124 /** 125 * Add a Callback interface for this holder. There can several Callback 126 * interfaces associated with a holder. 127 * 128 * @param callback The new Callback interface. 129 */ addCallback(Callback callback)130 public void addCallback(Callback callback); 131 132 /** 133 * Removes a previously added Callback interface from this holder. 134 * 135 * @param callback The Callback interface to remove. 136 */ removeCallback(Callback callback)137 public void removeCallback(Callback callback); 138 139 /** 140 * Use this method to find out if the surface is in the process of being 141 * created from Callback methods. This is intended to be used with 142 * {@link Callback#surfaceChanged}. 143 * 144 * @return true if the surface is in the process of being created. 145 */ isCreating()146 public boolean isCreating(); 147 148 /** 149 * Sets the surface's type. 150 * 151 * @deprecated this is ignored, this value is set automatically when needed. 152 */ 153 @Deprecated setType(int type)154 public void setType(int type); 155 156 /** 157 * Make the surface a fixed size. It will never change from this size. 158 * When working with a {@link SurfaceView}, this must be called from the 159 * same thread running the SurfaceView's window. 160 * 161 * @param width The surface's width. 162 * @param height The surface's height. 163 */ setFixedSize(int width, int height)164 public void setFixedSize(int width, int height); 165 166 /** 167 * Allow the surface to resized based on layout of its container (this is 168 * the default). When this is enabled, you should monitor 169 * {@link Callback#surfaceChanged} for changes to the size of the surface. 170 * When working with a {@link SurfaceView}, this must be called from the 171 * same thread running the SurfaceView's window. 172 */ setSizeFromLayout()173 public void setSizeFromLayout(); 174 175 /** 176 * Set the desired PixelFormat of the surface. The default is OPAQUE. 177 * When working with a {@link SurfaceView}, this must be called from the 178 * same thread running the SurfaceView's window. 179 * 180 * @param format A constant from PixelFormat. 181 * 182 * @see android.graphics.PixelFormat 183 */ setFormat(int format)184 public void setFormat(int format); 185 186 /** 187 * Enable or disable option to keep the screen turned on while this 188 * surface is displayed. The default is false, allowing it to turn off. 189 * This is safe to call from any thread. 190 * 191 * @param screenOn Set to true to force the screen to stay on, false 192 * to allow it to turn off. 193 */ setKeepScreenOn(boolean screenOn)194 public void setKeepScreenOn(boolean screenOn); 195 196 /** 197 * Start editing the pixels in the surface. The returned Canvas can be used 198 * to draw into the surface's bitmap. A null is returned if the surface has 199 * not been created or otherwise cannot be edited. You will usually need 200 * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 201 * to find out when the Surface is available for use. 202 * 203 * <p>The content of the Surface is never preserved between unlockCanvas() and 204 * lockCanvas(), for this reason, every pixel within the Surface area 205 * must be written. The only exception to this rule is when a dirty 206 * rectangle is specified, in which case, non-dirty pixels will be 207 * preserved. 208 * 209 * <p>If you call this repeatedly when the Surface is not ready (before 210 * {@link Callback#surfaceCreated Callback.surfaceCreated} or after 211 * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed}), your calls 212 * will be throttled to a slow rate in order to avoid consuming CPU. 213 * 214 * <p>If null is not returned, this function internally holds a lock until 215 * the corresponding {@link #unlockCanvasAndPost} call, preventing 216 * {@link SurfaceView} from creating, destroying, or modifying the surface 217 * while it is being drawn. This can be more convenient than accessing 218 * the Surface directly, as you do not need to do special synchronization 219 * with a drawing thread in {@link Callback#surfaceDestroyed 220 * Callback.surfaceDestroyed}. 221 * 222 * @return Canvas Use to draw into the surface. 223 */ lockCanvas()224 public Canvas lockCanvas(); 225 226 227 /** 228 * Just like {@link #lockCanvas()} but allows specification of a dirty rectangle. 229 * Every 230 * pixel within that rectangle must be written; however pixels outside 231 * the dirty rectangle will be preserved by the next call to lockCanvas(). 232 * 233 * @see android.view.SurfaceHolder#lockCanvas 234 * 235 * @param dirty Area of the Surface that will be modified. 236 * @return Canvas Use to draw into the surface. 237 */ lockCanvas(Rect dirty)238 public Canvas lockCanvas(Rect dirty); 239 240 /** 241 * Finish editing pixels in the surface. After this call, the surface's 242 * current pixels will be shown on the screen, but its content is lost, 243 * in particular there is no guarantee that the content of the Surface 244 * will remain unchanged when lockCanvas() is called again. 245 * 246 * @see #lockCanvas() 247 * 248 * @param canvas The Canvas previously returned by lockCanvas(). 249 */ unlockCanvasAndPost(Canvas canvas)250 public void unlockCanvasAndPost(Canvas canvas); 251 252 /** 253 * Retrieve the current size of the surface. Note: do not modify the 254 * returned Rect. This is only safe to call from the thread of 255 * {@link SurfaceView}'s window, or while inside of 256 * {@link #lockCanvas()}. 257 * 258 * @return Rect The surface's dimensions. The left and top are always 0. 259 */ getSurfaceFrame()260 public Rect getSurfaceFrame(); 261 262 /** 263 * Direct access to the surface object. The Surface may not always be 264 * available -- for example when using a {@link SurfaceView} the holder's 265 * Surface is not created until the view has been attached to the window 266 * manager and performed a layout in order to determine the dimensions 267 * and screen position of the Surface. You will thus usually need 268 * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 269 * to find out when the Surface is available for use. 270 * 271 * <p>Note that if you directly access the Surface from another thread, 272 * it is critical that you correctly implement 273 * {@link Callback#surfaceCreated Callback.surfaceCreated} and 274 * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed} to ensure 275 * that thread only accesses the Surface while it is valid, and that the 276 * Surface does not get destroyed while the thread is using it. 277 * 278 * <p>This method is intended to be used by frameworks which often need 279 * direct access to the Surface object (usually to pass it to native code). 280 * 281 * @return Surface The surface. 282 */ getSurface()283 public Surface getSurface(); 284 } 285