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 { 53 public BadSurfaceTypeException() { 54 } 55 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 322 public Surface getSurface(); 323 } 324
