public interface SurfaceHolder
SurfaceView
class.
When using this interface from a thread other than the one running
its SurfaceView
, you will want to carefully read the
methods
lockCanvas()
and Callback.surfaceCreated()
.
Modifier and Type | Interface and Description |
---|---|
static class |
SurfaceHolder.BadSurfaceTypeException
Exception that is thrown from
lockCanvas() when called on a Surface
whose type is SURFACE_TYPE_PUSH_BUFFERS. |
static interface |
SurfaceHolder.Callback
A client may implement this interface to receive information about
changes to the surface.
|
static interface |
SurfaceHolder.Callback2
Additional callbacks that can be received for
SurfaceHolder.Callback . |
Modifier and Type | Field and Description |
---|---|
static int |
SURFACE_TYPE_GPU
Deprecated.
this is ignored, this value is set automatically when needed.
|
static int |
SURFACE_TYPE_HARDWARE
Deprecated.
this is ignored, this value is set automatically when needed.
|
static int |
SURFACE_TYPE_NORMAL
Deprecated.
this is ignored, this value is set automatically when needed.
|
static int |
SURFACE_TYPE_PUSH_BUFFERS
Deprecated.
this is ignored, this value is set automatically when needed.
|
Modifier and Type | Method and Description |
---|---|
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 specification of 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)
Deprecated.
this is ignored, this value is set automatically when needed.
|
void |
unlockCanvasAndPost(Canvas canvas)
Finish editing pixels in the surface.
|
@Deprecated static final int SURFACE_TYPE_NORMAL
@Deprecated static final int SURFACE_TYPE_HARDWARE
@Deprecated static final int SURFACE_TYPE_GPU
@Deprecated static final int SURFACE_TYPE_PUSH_BUFFERS
void addCallback(SurfaceHolder.Callback callback)
callback
- The new Callback interface.void removeCallback(SurfaceHolder.Callback callback)
callback
- The Callback interface to remove.boolean isCreating()
SurfaceHolder.Callback.surfaceChanged(android.view.SurfaceHolder, int, int, int)
.@Deprecated void setType(int type)
void setFixedSize(int width, int height)
SurfaceView
, this must be called from the
same thread running the SurfaceView's window.width
- The surface's width.height
- The surface's height.void setSizeFromLayout()
SurfaceHolder.Callback.surfaceChanged(android.view.SurfaceHolder, int, int, int)
for changes to the size of the surface.
When working with a SurfaceView
, this must be called from the
same thread running the SurfaceView's window.void setFormat(int format)
SurfaceView
, this must be called from the
same thread running the SurfaceView's window.format
- A constant from PixelFormat.PixelFormat
void setKeepScreenOn(boolean screenOn)
screenOn
- Set to true to force the screen to stay on, false
to allow it to turn off.Canvas lockCanvas()
Callback.surfaceCreated
to find out when the Surface is available for use.
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(android.graphics.Canvas)
call, preventing
SurfaceView
from creating, destroying, or modifying the surface
while it is being drawn. This can be more convenient than accessing
the Surface directly, as you do not need to do special synchronization
with a drawing thread in Callback.surfaceDestroyed
.
Canvas lockCanvas(Rect dirty)
lockCanvas()
but allows specification of a dirty rectangle.
Every
pixel within that rectangle must be written; however pixels outside
the dirty rectangle will be preserved by the next call to lockCanvas().dirty
- Area of the Surface that will be modified.lockCanvas()
void unlockCanvasAndPost(Canvas canvas)
canvas
- The Canvas previously returned by lockCanvas().lockCanvas()
Rect getSurfaceFrame()
SurfaceView
's window, or while inside of
lockCanvas()
.Surface getSurface()
SurfaceView
the holder's
Surface is not created until the view has been attached to the window
manager and performed a layout in order to determine the dimensions
and screen position of the Surface. You will thus usually need
to implement Callback.surfaceCreated
to find out when the Surface is available for use.
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.