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. 276bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 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. 766bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 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}. 866bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 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 996bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * the surface, you must ensure that thread is no longer touching the 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface before returning from this function. 1016bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 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 * 11925cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * As of O, {@link #surfaceRedrawNeededAsync} may be implemented 12025cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * to provide a non-blocking implementation. If {@link #surfaceRedrawNeededAsync} 12125cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * is not implemented, then this will be called instead. 12225cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * 123d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn * @param holder The SurfaceHolder whose surface has changed. 124d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn */ 12525cfa134835e3791bdb6572f5e25cf4599015678Robert Carr void surfaceRedrawNeeded(SurfaceHolder holder); 12625cfa134835e3791bdb6572f5e25cf4599015678Robert Carr 12725cfa134835e3791bdb6572f5e25cf4599015678Robert Carr /** 12825cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * An alternative to surfaceRedrawNeeded where it is not required to block 12925cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * until the redraw is complete. You should initiate the redraw, and return, 13025cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * later invoking drawingFinished when your redraw is complete. 13125cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * 13225cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * This can be useful to avoid blocking your main application thread on rendering. 13325cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * 13425cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * As of O, if this is implemented {@link #surfaceRedrawNeeded} will not be called. 13525cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * However it is still recommended to implement {@link #surfaceRedrawNeeded} for 13625cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * compatibility with older versions of the platform. 13725cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * 13825cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * @param holder The SurfaceHolder which needs redrawing. 13925cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * @param drawingFinished A runnable to signal completion. This may be invoked 14025cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * from any thread. 14125cfa134835e3791bdb6572f5e25cf4599015678Robert Carr * 14225cfa134835e3791bdb6572f5e25cf4599015678Robert Carr */ 14325cfa134835e3791bdb6572f5e25cf4599015678Robert Carr default void surfaceRedrawNeededAsync(SurfaceHolder holder, Runnable drawingFinished) { 14425cfa134835e3791bdb6572f5e25cf4599015678Robert Carr surfaceRedrawNeeded(holder); 14525cfa134835e3791bdb6572f5e25cf4599015678Robert Carr drawingFinished.run(); 14625cfa134835e3791bdb6572f5e25cf4599015678Robert Carr } 147d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn } 148d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn 149d76b67c340d1564abf8d14d976fdaf83bf2b3320Dianne Hackborn /** 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Add a Callback interface for this holder. There can several Callback 151334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * interfaces associated with a holder. 1526bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param callback The new Callback interface. 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void addCallback(Callback callback); 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Removes a previously added Callback interface from this holder. 1596bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param callback The Callback interface to remove. 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void removeCallback(Callback callback); 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Use this method to find out if the surface is in the process of being 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * created from Callback methods. This is intended to be used with 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceChanged}. 1686bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return true if the surface is in the process of being created. 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean isCreating(); 1726bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 174d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian * Sets the surface's type. 1756bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 176d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian * @deprecated this is ignored, this value is set automatically when needed. 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 178d2112306330ce0c162bee4b864991962ca2b655aMathias Agopian @Deprecated 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setType(int type); 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Make the surface a fixed size. It will never change from this size. 183a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 1856bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param width The surface's width. 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param height The surface's height. 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setFixedSize(int width, int height); 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Allow the surface to resized based on layout of its container (this is 1939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the default). When this is enabled, you should monitor 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceChanged} for changes to the size of the surface. 195a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setSizeFromLayout(); 1999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set the desired PixelFormat of the surface. The default is OPAQUE. 202a45746efadd11bb7dfab026fb3c81a25fae74ca4Jeff Smith * When working with a {@link SurfaceView}, this must be called from the 2039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * same thread running the SurfaceView's window. 2046bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param format A constant from PixelFormat. 2066bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see android.graphics.PixelFormat 2089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setFormat(int format); 2109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Enable or disable option to keep the screen turned on while this 2139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * surface is displayed. The default is false, allowing it to turn off. 2149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * This is safe to call from any thread. 2156bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 216334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * @param screenOn Set to true to force the screen to stay on, false 2179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to allow it to turn off. 2189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setKeepScreenOn(boolean screenOn); 2206bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck 2219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Start editing the pixels in the surface. The returned Canvas can be used 2239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to draw into the surface's bitmap. A null is returned if the surface has 224334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * not been created or otherwise cannot be edited. You will usually need 2259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 2269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to find out when the Surface is available for use. 2276bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>The content of the Surface is never preserved between unlockCanvas() and 2299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * lockCanvas(), for this reason, every pixel within the Surface area 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * must be written. The only exception to this rule is when a dirty 231334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * rectangle is specified, in which case, non-dirty pixels will be 2329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preserved. 2336bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>If you call this repeatedly when the Surface is not ready (before 2359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceCreated Callback.surfaceCreated} or after 2369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed}), your calls 2379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be throttled to a slow rate in order to avoid consuming CPU. 2386bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>If null is not returned, this function internally holds a lock until 2409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the corresponding {@link #unlockCanvasAndPost} call, preventing 2419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SurfaceView} from creating, destroying, or modifying the surface 242334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * while it is being drawn. This can be more convenient than accessing 2439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the Surface directly, as you do not need to do special synchronization 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * with a drawing thread in {@link Callback#surfaceDestroyed 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Callback.surfaceDestroyed}. 2466bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Canvas Use to draw into the surface. 2489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Canvas lockCanvas(); 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2516bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck 2529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 253334031cd07c3bd09d23fce0ebaf946fc6ecfee26Glenn Kasten * Just like {@link #lockCanvas()} but allows specification of a dirty rectangle. 2549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Every 2559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * pixel within that rectangle must be written; however pixels outside 2569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the dirty rectangle will be preserved by the next call to lockCanvas(). 2576bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see android.view.SurfaceHolder#lockCanvas 2596bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param dirty Area of the Surface that will be modified. 2619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Canvas Use to draw into the surface. 2629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Canvas lockCanvas(Rect dirty); 2649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2666bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * <p>Just like {@link #lockCanvas()} but the returned canvas is hardware-accelerated. 2676bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2686bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * <p>See the <a href="{@docRoot}guide/topics/graphics/hardware-accel.html#unsupported"> 2696bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * unsupported drawing operations</a> for a list of what is and isn't 2706bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * supported in a hardware-accelerated canvas. 2716bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2726bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * @return Canvas Use to draw into the surface. 2736bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * @throws IllegalStateException If the canvas cannot be locked. 2746bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck */ 2756bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck default Canvas lockHardwareCanvas() { 2766bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck throw new IllegalStateException("This SurfaceHolder doesn't support lockHardwareCanvas"); 2776bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck } 2786bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck 2796bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck /** 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Finish editing pixels in the surface. After this call, the surface's 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * current pixels will be shown on the screen, but its content is lost, 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in particular there is no guarantee that the content of the Surface 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will remain unchanged when lockCanvas() is called again. 2846bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #lockCanvas() 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param canvas The Canvas previously returned by lockCanvas(). 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void unlockCanvasAndPost(Canvas canvas); 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve the current size of the surface. Note: do not modify the 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returned Rect. This is only safe to call from the thread of 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SurfaceView}'s window, or while inside of 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #lockCanvas()}. 2966bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Rect The surface's dimensions. The left and top are always 0. 2989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Rect getSurfaceFrame(); 3009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Direct access to the surface object. The Surface may not always be 3039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * available -- for example when using a {@link SurfaceView} the holder's 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface is not created until the view has been attached to the window 3059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * manager and performed a layout in order to determine the dimensions 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * and screen position of the Surface. You will thus usually need 3079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to implement {@link Callback#surfaceCreated Callback.surfaceCreated} 3089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to find out when the Surface is available for use. 3096bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 3109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that if you directly access the Surface from another thread, 3119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * it is critical that you correctly implement 3129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceCreated Callback.surfaceCreated} and 3139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Callback#surfaceDestroyed Callback.surfaceDestroyed} to ensure 3149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * that thread only accesses the Surface while it is valid, and that the 3159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Surface does not get destroyed while the thread is using it. 3166bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 3179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>This method is intended to be used by frameworks which often need 3189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * direct access to the Surface object (usually to pass it to native code). 3196bc701421047bf881ee16c49b242ea19ae4cd9b9John Reck * 3209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Surface The surface. 3219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public Surface getSurface(); 3239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 324