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