SurfaceHolder
public
interface
SurfaceHolder
| 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 other than the one running
its SurfaceView, you will want to carefully read the
methods
lockCanvas() and Callback.surfaceCreated().
Summary
Nested classes | |
|---|---|
class |
SurfaceHolder.BadSurfaceTypeException
Exception that is thrown from |
interface |
SurfaceHolder.Callback
A client may implement this interface to receive information about changes to the surface. |
interface |
SurfaceHolder.Callback2
Additional callbacks that can be received for |
Constants | |
|---|---|
int |
SURFACE_TYPE_GPU
This constant was deprecated in API level 15. this is ignored, this value is set automatically when needed. |
int |
SURFACE_TYPE_HARDWARE
This constant was deprecated in API level 15. this is ignored, this value is set automatically when needed. |
int |
SURFACE_TYPE_NORMAL
This constant was deprecated in API level 15. this is ignored, this value is set automatically when needed. |
int |
SURFACE_TYPE_PUSH_BUFFERS
This constant was deprecated in API level 15. this is ignored, this value is set automatically when needed. |
Public methods | |
|---|---|
abstract
void
|
addCallback(SurfaceHolder.Callback callback)
Add a Callback interface for this holder. |
abstract
Surface
|
getSurface()
Direct access to the surface object. |
abstract
Rect
|
getSurfaceFrame()
Retrieve the current size of the surface. |
abstract
boolean
|
isCreating()
Use this method to find out if the surface is in the process of being created from Callback methods. |
abstract
Canvas
|
lockCanvas()
Start editing the pixels in the surface. |
abstract
Canvas
|
lockCanvas(Rect dirty)
Just like |
default
Canvas
|
lockHardwareCanvas()
Just like |
abstract
void
|
removeCallback(SurfaceHolder.Callback callback)
Removes a previously added Callback interface from this holder. |
abstract
void
|
setFixedSize(int width, int height)
Make the surface a fixed size. |
abstract
void
|
setFormat(int format)
Set the desired PixelFormat of the surface. |
abstract
void
|
setKeepScreenOn(boolean screenOn)
Enable or disable option to keep the screen turned on while this surface is displayed. |
abstract
void
|
setSizeFromLayout()
Allow the surface to resized based on layout of its container (this is the default). |
abstract
void
|
setType(int type)
This method was deprecated in API level 15. this is ignored, this value is set automatically when needed. |
abstract
void
|
unlockCanvasAndPost(Canvas canvas)
Finish editing pixels in the surface. |
Constants
SURFACE_TYPE_GPU
public static final int SURFACE_TYPE_GPU
This constant was deprecated
in API level 15.
this is ignored, this value is set automatically when needed.
Constant Value: 2 (0x00000002)
SURFACE_TYPE_HARDWARE
public static final int SURFACE_TYPE_HARDWARE
This constant was deprecated
in API level 15.
this is ignored, this value is set automatically when needed.
Constant Value: 1 (0x00000001)
SURFACE_TYPE_NORMAL
public static final int SURFACE_TYPE_NORMAL
This constant was deprecated
in API level 15.
this is ignored, this value is set automatically when needed.
Constant Value: 0 (0x00000000)
SURFACE_TYPE_PUSH_BUFFERS
public static final int SURFACE_TYPE_PUSH_BUFFERS
This constant was deprecated
in API level 15.
this is ignored, this value is set automatically when needed.
Constant Value: 3 (0x00000003)
Public methods
addCallback
public abstract void addCallback (SurfaceHolder.Callback callback)
Add a Callback interface for this holder. There can several Callback interfaces associated with a holder.
| Parameters | |
|---|---|
callback |
SurfaceHolder.Callback: The new Callback interface. |
getSurface
public abstract Surface getSurface ()
Direct access to the surface object. The Surface may not always be
available -- for example when using a 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).
| Returns | |
|---|---|
Surface |
Surface The surface. |
getSurfaceFrame
public abstract Rect getSurfaceFrame ()
Retrieve the current size of the surface. Note: do not modify the
returned Rect. This is only safe to call from the thread of
SurfaceView's window, or while inside of
lockCanvas().
| Returns | |
|---|---|
Rect |
Rect The surface's dimensions. The left and top are always 0. |
isCreating
public abstract boolean isCreating ()
Use this method to find out if the surface is in the process of being
created from Callback methods. This is intended to be used with
Callback#surfaceChanged.
| Returns | |
|---|---|
boolean |
true if the surface is in the process of being created. |
lockCanvas
public abstract Canvas lockCanvas ()
Start editing the pixels in the surface. The returned Canvas can be used
to draw into the surface's bitmap. A null is returned if the surface has
not been created or otherwise cannot be edited. You will usually need
to implement 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(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.
| Returns | |
|---|---|
Canvas |
Canvas Use to draw into the surface. |
lockCanvas
public abstract Canvas lockCanvas (Rect dirty)
Just like 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().
| Parameters | |
|---|---|
dirty |
Rect: Area of the Surface that will be modified. |
| Returns | |
|---|---|
Canvas |
Canvas Use to draw into the surface. |
See also:
lockHardwareCanvas
public Canvas lockHardwareCanvas ()
Just like lockCanvas() but the returned canvas is hardware-accelerated.
See the unsupported drawing operations for a list of what is and isn't supported in a hardware-accelerated canvas.
| Returns | |
|---|---|
Canvas |
Canvas Use to draw into the surface. |
| Throws | |
|---|---|
IllegalStateException |
If the canvas cannot be locked. |
removeCallback
public abstract void removeCallback (SurfaceHolder.Callback callback)
Removes a previously added Callback interface from this holder.
| Parameters | |
|---|---|
callback |
SurfaceHolder.Callback: The Callback interface to remove. |
setFixedSize
public abstract void setFixedSize (int width,
int height)
Make the surface a fixed size. It will never change from this size.
When working with a SurfaceView, this must be called from the
same thread running the SurfaceView's window.
| Parameters | |
|---|---|
width |
int: The surface's width. |
height |
int: The surface's height. |
setFormat
public abstract void setFormat (int format)
Set the desired PixelFormat of the surface. The default is OPAQUE.
When working with a SurfaceView, this must be called from the
same thread running the SurfaceView's window.
| Parameters | |
|---|---|
format |
int: A constant from PixelFormat. |
See also:
setKeepScreenOn
public abstract void setKeepScreenOn (boolean screenOn)
Enable or disable option to keep the screen turned on while this surface is displayed. The default is false, allowing it to turn off. This is safe to call from any thread.
| Parameters | |
|---|---|
screenOn |
boolean: Set to true to force the screen to stay on, false
to allow it to turn off. |
setSizeFromLayout
public abstract void setSizeFromLayout ()
Allow the surface to resized based on layout of its container (this is
the default). When this is enabled, you should monitor
Callback#surfaceChanged 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.
setType
public abstract void setType (int type)
This method was deprecated
in API level 15.
this is ignored, this value is set automatically when needed.
Sets the surface's type.
| Parameters | |
|---|---|
type |
int |
unlockCanvasAndPost
public abstract void unlockCanvasAndPost (Canvas canvas)
Finish editing pixels in the surface. After this call, the surface's current pixels will be shown on the screen, but its content is lost, in particular there is no guarantee that the content of the Surface will remain unchanged when lockCanvas() is called again.
| Parameters | |
|---|---|
canvas |
Canvas: The Canvas previously returned by lockCanvas(). |
See also:
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-04 UTC.