android.view
Interface SurfaceHolder

public interface 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.

Nested Class Summary

static class	SurfaceHolder.BadSurfaceTypeException Exception that is thrown from lockCanvas() when called on a Surface whose is SURFACE_TYPE_PUSH_BUFFERS.
static interface	SurfaceHolder.Callback A client may implement this interface to receive information about changes to the surface.

Field Summary

static int	SURFACE_TYPE_GPU Surface type: creates a surface suited to be used with the GPU
static int	SURFACE_TYPE_HARDWARE Surface type: creates a suited to be used with DMA engines and hardware accelerators.
static int	SURFACE_TYPE_NORMAL Surface type: creates a regular surface, usually in main, non contiguous, cached/buffered RAM.
static int	SURFACE_TYPE_PUSH_BUFFERS Surface type: creates a "push" surface, that is a surface that doesn't owns its buffers.

Method Summary

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.

Field Detail

SURFACE_TYPE_NORMAL

static final int SURFACE_TYPE_NORMAL

Surface type: creates a regular surface, usually in main, non contiguous, cached/buffered RAM.

See Also:

Constant Field Values

SURFACE_TYPE_HARDWARE

static final int SURFACE_TYPE_HARDWARE

Surface type: creates a suited to be used with DMA engines and hardware accelerators.

See Also:

Constant Field Values

SURFACE_TYPE_GPU

static final int SURFACE_TYPE_GPU

Surface type: creates a surface suited to be used with the GPU

See Also:

Constant Field Values

SURFACE_TYPE_PUSH_BUFFERS

static final int SURFACE_TYPE_PUSH_BUFFERS

Surface type: creates a "push" surface, that is a surface that doesn't owns its buffers. With such a surface lockCanvas will fail.

See Also:

Constant Field Values

Method Detail

addCallback

void addCallback(SurfaceHolder.Callback callback)

Add a Callback interface for this holder. There can several Callback interfaces associated to a holder.

Parameters:

callback - The new Callback interface.

removeCallback

void removeCallback(SurfaceHolder.Callback callback)

Removes a previously added Callback interface from this holder.

Parameters:

callback - The Callback interface to remove.

isCreating

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 SurfaceHolder.Callback.surfaceChanged(android.view.SurfaceHolder, int, int, int).

Returns:

true if the surface is in the process of being created.

setType

void setType(int type)

Sets the surface's type. Surfaces intended to be used with OpenGL ES should be of SURFACE_TYPE_GPU, surfaces accessed by DMA engines and hardware accelerators should be of type SURFACE_TYPE_HARDWARE. Failing to set the surface's type appropriately could result in degraded performance or failure.

Parameters:

type - The surface's memory type.

setFixedSize

void setFixedSize(int width,
                  int height)

Make the surface a fixed size. It will never change from this size. When working with a {link SurfaceView}, this must be called from the same thread running the SurfaceView's window.

Parameters:

width - The surface's width.

height - The surface's height.

setSizeFromLayout

void setSizeFromLayout()

Allow the surface to resized based on layout of its container (this is the default). When this is enabled, you should monitor SurfaceHolder.Callback.surfaceChanged(android.view.SurfaceHolder, int, int, int) for changes to the size of the surface. When working with a {link SurfaceView}, this must be called from the same thread running the SurfaceView's window.

setFormat

void setFormat(int format)

Set the desired PixelFormat of the surface. The default is OPAQUE. When working with a {link SurfaceView}, this must be called from the same thread running the SurfaceView's window.

Parameters:

format - A constant from PixelFormat.

See Also:

PixelFormat

setKeepScreenOn

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. Enabling the option effectivelty. This is safe to call from any thread.

Parameters:

screenOn - Supply to true to force the screen to stay on, false to allow it to turn off.

lockCanvas

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 can not 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(android.graphics.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.

Returns:

Canvas Use to draw into the surface.

lockCanvas

Canvas lockCanvas(Rect dirty)

Just like lockCanvas() but allows to specify 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 - Area of the Surface that will be modified.

Returns:

Canvas Use to draw into the surface.

See Also:

lockCanvas()

unlockCanvasAndPost

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 - The Canvas previously returned by lockCanvas().

See Also:

android.view.SurfaceHolder.lockCanvas

getSurfaceFrame

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 The surface's dimensions. The left and top are always 0.

getSurface

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). 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.

Returns:

Surface The surface.