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 Use to draw into the surface.

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