android.view.SurfaceHolder |
Abstract interface to someone holding a display surface. Allows you to control the surface size and format, edit the pixels in the surface, and monitor changes to the surface. This interface is typically available through the SurfaceView class.
When using this interface from a thread different than the one running its SurfaceView, you will want to carefully read the lockCanvas() and Callback.surfaceCreated.
SurfaceHolder.BadSurfaceTypeException | Exception that is thrown from lockCanvas() when called on a Surface whose is SURFACE_TYPE_PUSH_BUFFERS. |
SurfaceHolder.Callback | A client may implement this interface to receive information about changes to the surface. |
Value | ||||
---|---|---|---|---|
int | SURFACE_TYPE_GPU | Surface type: creates a surface suited to be used with the GPU | 2 | 0x00000002 |
int | SURFACE_TYPE_HARDWARE | Surface type: creates a suited to be used with DMA engines and hardware accelerators. | 1 | 0x00000001 |
int | SURFACE_TYPE_NORMAL | Surface type: creates a regular surface, usually in main, non contiguous, cached/buffered RAM. | 0 | 0x00000000 |
int | SURFACE_TYPE_PUSH_BUFFERS | Surface type: creates a "push" surface, that is a surface that doesn't owns its buffers. | 3 | 0x00000003 |
void | addCallback(SurfaceHolder.Callback callback) | |||||
Add a Callback interface for this holder. | ||||||
Surface | getSurface() | |||||
Direct access to the surface object. | ||||||
Rect | getSurfaceFrame() | |||||
Retrieve the current size of the surface. | ||||||
boolean | isCreating() | |||||
Use this method to find out if the surface is in the process of being created from Callback methods. | ||||||
Canvas | lockCanvas() | |||||
Start editing the pixels in the surface. | ||||||
Canvas | lockCanvas(Rect dirty) | |||||
Just like lockCanvas() but allows to specify a dirty rectangle. | ||||||
void | removeCallback(SurfaceHolder.Callback callback) | |||||
Removes a previously added Callback interface from this holder. | ||||||
void | setFixedSize(int width, int height) | |||||
Make the surface a fixed size. | ||||||
void | setFormat(int format) | |||||
Set the desired PixelFormat of the surface. | ||||||
void | setKeepScreenOn(boolean screenOn) | |||||
Enable or disable option to keep the screen turned on while this surface is displayed. | ||||||
void | setSizeFromLayout() | |||||
Allow the surface to resized based on layout of its container (this is the default). | ||||||
void | setType(int type) | |||||
Sets the surface's type. | ||||||
void | unlockCanvasAndPost(Canvas canvas) | |||||
Finish editing pixels in the surface. |
callback | The new Callback interface. |
---|
Note that if you directly access the Surface from another thread, it is critical that you correctly implement Callback.surfaceCreated and Callback.surfaceDestroyed to ensure that thread only accesses the Surface while it is valid, and that the Surface does not get destroyed while the thread is using it.
This method is intended to be used by frameworks which often need direct access to the Surface object (usually to pass it to native code). When designing APIs always use SurfaceHolder to pass surfaces around as opposed to the Surface object itself. A rule of thumb is that application code should never have to call this method.
The content of the Surface is never preserved between unlockCanvas() and lockCanvas(), for this reason, every pixel within the Surface area must be written. The only exception to this rule is when a dirty rectangle is specified, in which case, non dirty pixels will be preserved.
If you call this repeatedly when the Surface is not ready (before Callback.surfaceCreated or after Callback.surfaceDestroyed), your calls will be throttled to a slow rate in order to avoid consuming CPU.
If null is not returned, this function internally holds a lock until the corresponding unlockCanvasAndPost(Canvas) call, preventing SurfaceView from creating, destroying, or modifying the surface while it is being drawn. This can be more convenience than accessing the Surface directly, as you do not need to do special synchronization with a drawing thread in Callback.surfaceDestroyed.
dirty | Area of the Surface that will be modified. |
---|
callback | The Callback interface to remove. |
---|
width | The surface's width. |
---|---|
height | The surface's height. |
format | A constant from PixelFormat. |
---|
screenOn | Supply to true to force the screen to stay on, false to allow it to turn off. |
---|
type | The surface's memory type. |
---|
canvas | The Canvas previously returned by lockCanvas(). |
---|
Copyright 2007 Google Inc. | Build 0.9_r1-98467 - 14 Aug 2008 18:48 |