19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2006 The Android Open Source Project 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you may not use this file except in compliance with the License. 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * You may obtain a copy of the License at 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * See the License for the specific language governing permissions and 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * limitations under the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.view; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.graphics.Canvas; 209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.graphics.Rect; 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Abstract interface to someone holding a display surface. Allows you to 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * control the surface size and format, edit the pixels in the surface, and 259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * monitor changes to the surface. This interface is typically available 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * through the {@link SurfaceView} class. 279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 28334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * <p>When using this interface from a thread other than the one running 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * its {@link SurfaceView}, you will want to carefully read the 30334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * methods 31334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * {@link #lockCanvas} and {@link Callback#surfaceCreated Callback.surfaceCreated()}. 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic interface SurfaceHolder { 34d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian 35d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian /** @deprecated this is ignored, this value is set automatically when needed. */ 36317a6280cc109e873646e4652be1582d870eedfdMathias Agopian @Deprecated 37d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian public static final int SURFACE_TYPE_NORMAL = 0; 38d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian /** @deprecated this is ignored, this value is set automatically when needed. */ 39d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian @Deprecated 40d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian public static final int SURFACE_TYPE_HARDWARE = 1; 41d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian /** @deprecated this is ignored, this value is set automatically when needed. */ 42d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian @Deprecated 43d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian public static final int SURFACE_TYPE_GPU = 2; 44d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian /** @deprecated this is ignored, this value is set automatically when needed. */ 45317a6280cc109e873646e4652be1582d870eedfdMathias Agopian @Deprecated 46d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian public static final int SURFACE_TYPE_PUSH_BUFFERS = 3; 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Exception that is thrown from {@link #lockCanvas} when called on a Surface 50334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * whose type is SURFACE_TYPE_PUSH_BUFFERS. 519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public static class BadSurfaceTypeException extends RuntimeException { 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public BadSurfaceTypeException() { 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public BadSurfaceTypeException(String name) { 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super(name); 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * A client may implement this interface to receive information about 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * changes to the surface. When used with a {@link SurfaceView}, the 649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface being held is only available between calls to 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #surfaceCreated(SurfaceHolder)} and 66334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * {@link #surfaceDestroyed(SurfaceHolder)}. The Callback is set with 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SurfaceHolder#addCallback SurfaceHolder.addCallback} method. 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public interface Callback { 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is called immediately after the surface is first created. 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Implementations of this should start up whatever rendering code 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * they desire. Note that only one thread can ever draw into 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a {@link Surface}, so you should not draw into the Surface here 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * if your normal rendering will be in another thread. 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param holder The SurfaceHolder whose surface is being created. 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void surfaceCreated(SurfaceHolder holder); 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is called immediately after any structural changes (format or 839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * size) have been made to the surface. You should at this point update 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the imagery in the surface. This method is always called at least 859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * once, after {@link #surfaceCreated}. 869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param holder The SurfaceHolder whose surface has changed. 889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param format The new PixelFormat of the surface. 899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param width The new width of the surface. 909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param height The new height of the surface. 919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void surfaceChanged(SurfaceHolder holder, int format, int width, 939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project int height); 949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is called immediately before a surface is being destroyed. After 979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returning from this call, you should no longer try to access this 989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * surface. If you have a rendering thread that directly accesses 999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the surface, you must ensure that thread is no longer touching the 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface before returning from this function. 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param holder The SurfaceHolder whose surface is being destroyed. 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void surfaceDestroyed(SurfaceHolder holder); 1059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 108d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * Additional callbacks that can be received for {@link Callback}. 109d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn */ 110d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn public interface Callback2 extends Callback { 111d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn /** 112d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * Called when the application needs to redraw the content of its 113d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * surface, after it is resized or for some other reason. By not 114334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * returning from here until the redraw is complete, you can ensure that 115d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * the user will not see your surface in a bad state (at its new 116d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * size before it has been correctly drawn that way). This will 117d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * typically be preceeded by a call to {@link #surfaceChanged}. 118d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * 119d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * @param holder The SurfaceHolder whose surface has changed. 120d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn */ 121d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn public void surfaceRedrawNeeded(SurfaceHolder holder); 122d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn } 123d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn 124d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn /** 1259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Add a Callback interface for this holder. There can several Callback 126334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * interfaces associated with a holder. 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param callback The new Callback interface. 1299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void addCallback(Callback callback); 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Removes a previously added Callback interface from this holder. 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param callback The Callback interface to remove. 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void removeCallback(Callback callback); 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Use this method to find out if the surface is in the process of being 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * created from Callback methods. This is intended to be used with 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceChanged}. 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return true if the surface is in the process of being created. 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean isCreating(); 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 149d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian * Sets the surface's type. 150d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian * 151d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian * @deprecated this is ignored, this value is set automatically when needed. 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 153d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian @Deprecated 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setType(int type); 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Make the surface a fixed size. It will never change from this size. 158a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param width The surface's width. 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param height The surface's height. 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setFixedSize(int width, int height); 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Allow the surface to resized based on layout of its container (this is 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the default). When this is enabled, you should monitor 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceChanged} for changes to the size of the surface. 170a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setSizeFromLayout(); 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set the desired PixelFormat of the surface. The default is OPAQUE. 177a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param format A constant from PixelFormat. 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see android.graphics.PixelFormat 1839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setFormat(int format); 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Enable or disable option to keep the screen turned on while this 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * surface is displayed. The default is false, allowing it to turn off. 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is safe to call from any thread. 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 191334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * @param screenOn Set to true to force the screen to stay on, false 1929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to allow it to turn off. 1939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setKeepScreenOn(boolean screenOn); 1959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Start editing the pixels in the surface. The returned Canvas can be used 1989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to draw into the surface's bitmap. A null is returned if the surface has 199334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * not been created or otherwise cannot be edited. You will usually need 2009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 2019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to find out when the Surface is available for use. 2029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The content of the Surface is never preserved between unlockCanvas() and 2049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * lockCanvas(), for this reason, every pixel within the Surface area 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * must be written. The only exception to this rule is when a dirty 206334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * rectangle is specified, in which case, non-dirty pixels will be 2079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preserved. 2089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>If you call this repeatedly when the Surface is not ready (before 2109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceCreated Callback.surfaceCreated} or after 2119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed}), your calls 2129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be throttled to a slow rate in order to avoid consuming CPU. 2139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>If null is not returned, this function internally holds a lock until 2159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the corresponding {@link #unlockCanvasAndPost} call, preventing 2169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SurfaceView} from creating, destroying, or modifying the surface 217334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * while it is being drawn. This can be more convenient than accessing 2189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Surface directly, as you do not need to do special synchronization 2199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * with a drawing thread in {@link Callback#surfaceDestroyed 2209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Callback.surfaceDestroyed}. 2219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Canvas Use to draw into the surface. 2239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Canvas lockCanvas(); 2259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 228334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * Just like {@link #lockCanvas()} but allows specification of a dirty rectangle. 2299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Every 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * pixel within that rectangle must be written; however pixels outside 2319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the dirty rectangle will be preserved by the next call to lockCanvas(). 2329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see android.view.SurfaceHolder#lockCanvas 2349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param dirty Area of the Surface that will be modified. 2369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Canvas Use to draw into the surface. 2379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Canvas lockCanvas(Rect dirty); 2399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Finish editing pixels in the surface. After this call, the surface's 2429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * current pixels will be shown on the screen, but its content is lost, 2439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in particular there is no guarantee that the content of the Surface 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will remain unchanged when lockCanvas() is called again. 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #lockCanvas() 2479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param canvas The Canvas previously returned by lockCanvas(). 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void unlockCanvasAndPost(Canvas canvas); 2519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve the current size of the surface. Note: do not modify the 2549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returned Rect. This is only safe to call from the thread of 2559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SurfaceView}'s window, or while inside of 2569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #lockCanvas()}. 2579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Rect The surface's dimensions. The left and top are always 0. 2599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Rect getSurfaceFrame(); 2619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Direct access to the surface object. The Surface may not always be 2649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * available -- for example when using a {@link SurfaceView} the holder's 2659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface is not created until the view has been attached to the window 2669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * manager and performed a layout in order to determine the dimensions 2679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and screen position of the Surface. You will thus usually need 2689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 2699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to find out when the Surface is available for use. 2709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that if you directly access the Surface from another thread, 2729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * it is critical that you correctly implement 2739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceCreated Callback.surfaceCreated} and 2749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed} to ensure 2759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * that thread only accesses the Surface while it is valid, and that the 2769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface does not get destroyed while the thread is using it. 2779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>This method is intended to be used by frameworks which often need 2799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * direct access to the Surface object (usually to pass it to native code). 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Surface The surface. 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Surface getSurface(); 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 285