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.

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

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

lockCanvas

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

setSizeFromLayout

Allow the surface to resized based on layout of its container (this is
the default). When this is enabled, you should monitor
surfaceChanged(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.

unlockCanvasAndPost

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.