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