SurfaceHolder

版本：Android 2.2 r1

结构

继承关系

public interface SurfaceHolder

android.view.SurfaceHolder

概述

抽象接口持有人显示表面。允许您控制面的大小和格式，编辑在suface的橡树，并监测到变化。此接口通常可通过SurfaceView类来实现。

当一个线程使用不同于正在运行的线程的SurfaceView的接口时，你应该仔细阅读lockCanvas()和Callback.surfaceCreated()这两个抽象函数

常量值

public static final int SURFACE_TYPE_GPU

常数已声明不赞成使用，已过时。

被忽略，该常量值在需要时自动设置。

Surface类型：创建适用于GPU加速的Surface

常量值：2 (0x00000002)

public static final int SURFACE_TYPE_HARDWARE

常数已声明不赞成使用，已过时。

被忽略，该常量值在需要时自动设置。

Surface类型：创建适用于DMA(Direct memory access )引擎和硬件加速的Surface

常量值：1 (0x00000001)

public static final int SURFACE_TYPE_NORMAL

Surface类型：创建用RAM缓存原生数据的普通Surface

常量值：0 (0x00000000)

public static final int SURFACE_TYPE_PUSH_BUFFERS

Surface类型：创建一个不包含原生数据Surface，Surface用到的数据由其他对象提供。如果设置这种类型则就不能调用lockCanvas来获取Canvas对象了，否则将出现错误。

常量值：3 (0x00000003)

公共方法

public abstract void addCallback (SurfaceHolder.Callback callback)

给Surface持有者添加回调接口，一个持有者可以关联多个回调接口。

参数

callback 新的回调接口

public abstract Surface getSurface ()

直接获取Surface对象，这个Surface对象并不总是能获取的。

例如：当使用SurfaceView, Surface的持有者直到该View隶属于当前窗口管理器，确认布局大小和屏幕的位置后才进行创建，你通常需要实现Callback.surfaceCreated寻找出可用的Surface。

注意，如果你通过另外的线程直接访问Surface ，关键在于你正确的实现了Callback.surfaceCreated 和Callback.surfaceDestroyed 函数来确保你访问的线程的Surface是可用的，有效的，当一个线程正在使用该Surface，将不能得到释放，销毁。

这个方法的目的是用于经常需要直接访问Surface对象的框架（通常是通过本地代码），在设计API时总使用SurfaceHolder来改变Surface，而不是Surface对象本身。一个经验规则是应用程序代码不能调用该方法

Surface对象

public abstract Rect getSurfaceFrame ()

检索当前Surface的大小

注意：不能修改发挥矩形区域大小，这是唯一安全的调用从SurfaceView的窗口线程，否则就需要放在lockCanvas()里面调用。

Suface的矩形尺寸，左侧和顶部总为0

public abstract boolean isCreating ()

使用这个方法是来确定在进程中的Surface是否通过Callback方法正被创建，这是为了确定surfaceChanged(SurfaceHolder, int, int, int).方法是否能用。

True 进程里的Suface正被创建

public abstract Canvas lockCanvas ()

开始编辑surface的像素，返回可以用来画到表面的位图的Canvas。如果表面尚未建立或无法进行编辑将返回null。通常需要实现Callback.surfaceCreated找出Surface时方可使用。

Surface的内容再从调用unlockCanvas() 和 lockCanvas(),之间被保存，为此，在Surface区域内的没有个像素都将被画出，仅一个例外是当脏矩形被指定的时候，非脏像素将会被保存。

如果当Surface没有初始化（Callback.surfaceCreated之前或者Callback.surfaceDestroyed之后），你反复调用它，为了避免耗费CPU，这些调用将以缓慢的速度被杀死。

如果没有返回null值，这个函数在内部直到调用unlockCanvasAndPost(Canvas)函数，才持有锁，来防止SurfaceView在绘制的时候被创建，销毁，或者修改surface，因为当调用Callback.surfaceDestroyed你不需要创建一个特殊的同步绘制线程所以你能更方便的直接访问这个Sufrace

用来进行绘制的Canvas

public abstract Canvas lockCanvas (Rect dirty)

和lockCanvas()一样，但允许指定一个脏矩形，再这个矩形的每个像素都必须被绘制，脏矩形外的像素将被保存直到下次调用lockCanvas()。

参数

dirty 将被修改的Surface区域

用来进行绘制的Canvas

参见

lockCanvas ()

public abstract void removeCallback (SurfaceHolder.Callback callback)

从Surface持有者中删除先前添加的回调接口

参数

callback 要删除的回调接口

public abstract void setFixedSize (int width, int height)

使surface固定大小，他将永远不能该表大小，当和SurfaceView一起工作时，这必须被同一运行的SurfaceView的窗口线程来调用

参数

width surface的宽.

height surface的高.

public abstract void setFormat (int format)

设置surface所需的像素格式。默认是不透明的，当和SurfaceView一起工作时，这必须被同一运行的SurfaceView的窗口线程来调用

参数

format PixelFormat的常量.

参见

PixelFormat

public abstract void setKeepScreenOn (boolean screenOn)

当surface被显示的时候是否启用或禁用屏幕保持打开状态，默认是禁用，允许屏幕关闭，启用选项有效时，可以安全的调用任何线程。

参数

screenOn 为ture时强制屏幕保持打开状态，fasle允许气关闭

public abstract void setSizeFromLayout ()

允许suface基于容器的布局来改变大小（这是默认的），当启用此功能，就应该监视surfaceChanged(SurfaceHolder, int, int, int)应对suface的大小变化，当和SurfaceView一起工作时，这必须被同一运行的SurfaceView的窗口线程来调用

public abstract void setType (int type)

设置该surface的类型

参数

type 该surface的内存类型

public abstract void unlockCanvasAndPost (Canvas canvas)

在surface完成编辑像素，该函数调用后，surface的当前像素就会在屏幕上显示，但是它的数据会丢失，尤其是没有保证surface数据保持不变的时候再次调用lockCanvas()。

参数

canvas 先前调用lockCanvas()返回的Canvas

参考

lockCanvas()

补充

在用SurfaceView进行游戏开发过程中，用到SurfaceHolder来处理它的Canvas上画的效果和动画是必不可少的。用于控制表面，大小，像素等。其中特别要注意以下的几个函数：
abstract void addCallback(SurfaceHolder.Callback callback);

// 给SurfaceView当前的持有者一个回调对象。

abstract Canvas lockCanvas();

// 锁定画布，一般在锁定后就可以通过其返回的画布对象Canvas，在其上面画图等操作了。

abstract Canvas lockCanvas(Rect dirty);

// 锁定画布的某个区域进行画图等..因为画完图后，会调用下面的unlockCanvasAndPost来改变显示内容。
// 相对部分内存要求比较高的游戏来说，可以不用重画dirty外的其它区域的像素，可以提高速度。

abstract void unlockCanvasAndPost(Canvas canvas);
// 结束锁定画图，并提交改变。

在android中开发游戏，一般来说，或想写一个复杂一点的游戏，是必须用到SurfaceView来开发的。

经过这一阵子对android的学习，我找到了自已在android中游戏开发的误区，不要老想着用Layout和view去实现，不要将某个游戏

中的对象做成一个组件来处理。应该尽量想着在Canvas(画布)中画出游戏戏中的背景、人物、动画等...

SurfaceView提供直接访问一个可画图的界面，可以控制在界面顶部的子视图层。SurfaceView是提供给需要直接画像素而不是使用

窗体部件的应用使用的。Android图形系统中一个重要的概念和线索是surface。View及其子类（如TextView, Button）

要画在surface上。每个surface创建一个Canvas对象（但属性时常改变），用来管理view在surface上的绘图操作，如画点画线。

还要注意的是，使用它的时候，一般都是出现在最顶层的

使用的SurfaceView的时候，一般情况下还要对其进行创建，销毁，改变时的情况进行监视，这就要用到SurfaceHolder.Callback.

1、Surface

Surface

extends Object
implements Parcelable

java.lang.Object
↳	android.view.Surface

Class Overview

Handle onto a raw buffer that is being managed by the screen compositor.

简单翻译：

Surface是原始图像缓冲区（raw buffer）的一个句柄，而原始图像缓冲区是由屏幕图像合成器（screen compositor）管理的。

1.1、就如在C语言编程一样，通过一个文件的句柄，就可以操作文件，获取文件的内容。同样的，通过Surface就可以获取raw buffer其中的内容。原生缓冲区（raw buffer）存储着当前窗口的像素数据。

1.2、事实上，当得到一个Surface对象时，同时会得到一个Canvas（画布）对象。这一点可以通过查看\frameworks\base\core\Java\Android\view\Surface.java文件可知道Surface类定义了一个Canvas成员变量

[java]  view plain copy  
 print ? 
 //@\frameworks\base\core\java\android\view\Surface.java  
 // The mSurfaceControl will only be present for Surfaces used by the window  
 // server or system processes. When this class is parceled we defer to the  
 // mSurfaceControl to do the parceling. Otherwise we parcel the  
 // mNativeSurface.  
 private int mSurfaceControl;  
 private int mSaveCount;  
 private Canvas mCanvas;  
 private int mNativeSurface;  
 private int mSurfaceGenerationId;  
 private String mName;  

1.3、理解Canvas对象，可以把它当做画布，Canvas的方法大多数是设置画布的大小、形状、画布背景颜色等等，要想在画布上面画画，一般要与Paint对象结合使用，顾名思义，Paint就是画笔的风格，颜料的色彩之类的。

[java]  view plain copy  
 print ? 
 // 创建画笔    
 Paint paint = new Paint();    
 paint.setColor(Color.RED);// 设置红色    
   
 canvas.drawCircle(60, 20, 10, paint);// 画一个圆    

1.4、Surface本身的作用类似一个句柄，得到了这个句柄就可以得到其中的Canvas、原生缓冲器以及其它方面的内容。

1.5、Surface实现了Parcelable接口，（implements Parcelable），也就是说Surface对象可以把显示内容的数据写入到 Parcel 中，并且能够从Parcel读回数据。

Parcelable

android.os.Parcelable

Known Indirect Subclasses

AbsSavedState, AbsoluteSizeSpan, AccessibilityEvent, AccessibilityNodeInfo, AccessibilityServiceInfo, Account, AccountAuthenticatorResponse, ActivityInfo, ActivityManager.MemoryInfo, ActivityManager.ProcessErrorStateInfo, ActivityManager.RecentTaskInfo, ActivityManager.RunningAppProcessInfo, ActivityManager.RunningServiceInfo, ActivityManager.RunningTaskInfo, and 144 others.

Class Overview

Interface for classes whose instances can be written to and restored from a Parcel. Classes implementing the Parcelable interface must also have a static field calledCREATOR, which is an object implementing theParcelable.Creator interface.

简单翻译：
实现这个接口的对象可以写入数据到Parcel，同时也可以把数据读出来。

2、SurfaceView

SurfaceView

extends View

java.lang.Object
↳	android.view.View
	↳	android.view.SurfaceView

Known Direct Subclasses

GLSurfaceView, RSSurfaceView, VideoView

Class Overview

Provides a dedicated drawing surface embedded inside of a view hierarchy. You can control the format of this surface and, if you like, its size; the SurfaceView takes care of placing the surface at the correct location on the screen

The surface is Z ordered so that it is behind the window holding its SurfaceView; the SurfaceView punches a hole in its window to allow its surface to be displayed. The view hierarchy will take care of correctly compositing with the Surface any siblings of the SurfaceView that would normally appear on top of it. This can be used to place overlays such as buttons on top of the Surface, though note however that it can have an impact on performance since a full alpha-blended composite will be performed each time the Surface changes.

Access to the underlying surface is provided via the SurfaceHolder interface, which can be retrieved by callinggetHolder().

The Surface will be created for you while the SurfaceView's window is visible; you should implementsurfaceCreated(SurfaceHolder)andsurfaceDestroyed(SurfaceHolder) to discover when the Surface is created and destroyed as the window is shown and hidden.

One of the purposes of this class is to provide a surface in which a secondary thread can render into the screen. If you are going to use it this way, you need to be aware of some threading semantics:

All SurfaceView and SurfaceHolder.Callback methods will be called from the thread running the SurfaceView's window (typically the main thread of the application). They thus need to correctly synchronize with any state that is also touched by the drawing thread.
You must ensure that the drawing thread only touches the underlying Surface while it is valid -- betweenSurfaceHolder.Callback.surfaceCreated() andSurfaceHolder.Callback.surfaceDestroyed().

简单翻译：

         SurfaceView提供了一个专门用于绘制的surface，这个surface内嵌于。你可以控制这个Surface的格式和尺寸。Surfaceview控制这个Surface在屏幕的正确绘制位置。

        surface是Z-ordered的（也就是说在xyz坐标系中，按照Z坐标排序的，Z值大的表面覆盖在Z值小的表面的上方），这表明它总在自己所在窗口的后面。surfaceview在显示窗口处为Surface提供了一个可见区域，通过这个区域，才能看到Surface里面的内容。可以放置一些覆盖图层（overlays）在Surface上面，如Button、Textview之类的。但是，需要注意的是，如果Surface上面有全透明的控件，那么随着Surface的每一次变化，这些全透明的控件就会重新渲染，这样的话，就影响性能与显示的效果。

        你可以通过SurfaceHolder这个接口去访问Surface，而执行getHolder()方法可以得到SurfaceHolder接口。

        当SurfaceView的窗口可见时，Surface就会被创建，当SurfaceView窗口隐藏时，Surface就会被销毁。当然了，你也可以通过复写surfaceCreated(SurfaceHolder) 和 surfaceDestroyed(SurfaceHolder) 这两个方法来验证一下Surface何时被创建与何时被销毁。

        SurfaceView提供了一个运行在渲染线程的surface，若你要更新屏幕，你需要了解以下线程知识。

所有SurfaceView 和 SurfaceHolder.Callback的方法都应该在主线程（UI线程）里面调用，应该要确保渲染进程所访问变量的同步性。
你必须确保只有当Surface有效的时候，（也就是当Surface的生命周期在SurfaceHolder.Callback.surfaceCreated() 和SurfaceHolder.Callback.surfaceDestroyed()之间）才能让渲染进程访问。

2.1、SurfaceView与Surface的联系

简单来说，SurfaceView与Surface的联系就是，Surface是管理显示内容的数据（implementsParcelable），包括存储于数据的交换。而SurfaceView就是把这些数据显示出来到屏幕上面。

两者联系如图所示：

3、SurfaceHolder

SurfaceHolder

android.view.SurfaceHolder

Class Overview

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

When using this interface from a thread other than the one running its SurfaceView, you will want to carefully read the methodslockCanvas()andCallback.surfaceCreated().

简单翻译：

SurfaceHolder是控制surface的一个抽象接口，你可以通过SurfaceHolder来控制surface的尺寸和格式，或者修改surface的像素，监视surface的变化等等，SurfaceHolder是SurfaceView的典型接口。

与直接控制SurfaceView来修改surface不同，使用SurfaceHolder来修改surface时，需要注意lockCanvas() 和Callback.surfaceCreated().这两个方法。

SurfaceHolder控制surface的流程所使用的几个方法。

3.1、abstract void   addCallback(SurfaceHolder.Callback callback)
             Add a Callback interface for this holder.// 给SurfaceHolder一个回调对象。

3.2、abstract Canvas   lockCanvas(Rect dirty)
             Just like lockCanvas() but allows specification of a dirty rectangle.
             // 锁定画布中的某一个区域，返回的画布对象Canvas（当更新的内容只有一个区域时，同时要追求高效，可以只更
           新一部分的区域，而不必更新全部画布区域）

3.3、abstract Canvas   lockCanvas()
             Start editing the pixels in the surface.// 锁定画布，返回的画布对象Canvas

3.4、abstract void   removeCallback(SurfaceHolder.Callback callback)
             Removes a previously added Callback interface from this holder.//移除回调对象

3.5、abstract void   unlockCanvasAndPost(Canvas canvas)
             Finish editing pixels in the surface.// 结束锁定画图，并提交改变。

4、SurfaceHolder.Callback

SurfaceHolder.Callback

android.view.SurfaceHolder.Callback

Known Indirect Subclasses

GLSurfaceView, NativeActivity, RSSurfaceView, SurfaceHolder.Callback2

Class Overview

A client may implement this interface to receive information about changes to the surface. When used with aSurfaceView, the Surface being held is only available between calls tosurfaceCreated(SurfaceHolder)andsurfaceDestroyed(SurfaceHolder). The Callback is set withSurfaceHolder.addCallback method.

简单翻译：

SurfaceHolder.Callback是监听surface改变的一个接口

4.1、public abstract voidsurfaceChanged(SurfaceHolder holder, int format, int width, int height)

holder	The SurfaceHolder whose surface has changed.
format	The new PixelFormat of the surface.
width	The new width of the surface.
height	The new height of the surfa

//surface发生改变时被调用

4.2、public abstract voidsurfaceCreated(SurfaceHolder holder)

Parameters

holder	The SurfaceHolder whose surface is being created

//在surface创建时被调用，一般在这个方法里面开启渲染屏幕的线程。

4.3、public abstract voidsurfaceDestroyed(SurfaceHolder holder)

Parameters

holder	The SurfaceHolder whose surface is being destroyed.

//销毁时被调用，一般在这个方法里将渲染的线程停止。

附上上述所说几种的联系方法

[java]  view plain copy  
 print ? 
 SurfaceHolder = SurfaceView.getHolder();  
   
 Surface = SurfaceHolder.getSurface();  
   
 Canvas =SurfaceHolder.LockCanvas(Rect dirty)  
   
 Canvas   =Surface.lockCanvas(Rect dirty)  

5、Demo小程序

共有两个class效果图如下，具体看代码和注释。

进入程序，执行

[java]  view plain copy  
 print ? 
 public void surfaceCreated(SurfaceHolder holder)  

然后执行

[java]  view plain copy  
 print ? 
 public void surfaceChanged(SurfaceHolder holder, int format, int width,  int height)  

退出程序调用surfaceDestroyed，释放资源。

[java]  view plain copy  
 print ? 
 public void surfaceDestroyed(SurfaceHolder holder)  

/****************************************************************/

效果图：

@MySurfaceView.java

[java]  view plain copy  
 print ? 
 /* 
  * author: conowen 
  * e-mail: conowen@hotmail.com 
  * date  :  2012.8.4 
  */  
 package com.conowen.SurfaceViewDemo;  
   
 import android.app.Activity;  
 import android.os.Bundle;  
   
 public class SurfaceViewDemoActivity extends Activity {  
     /** Called when the activity is first created. */  
     @Override  
     public void onCreate(Bundle savedInstanceState) {  
         super.onCreate(savedInstanceState);  
        // setContentView(R.layout.main);  
         setContentView(new MySurfaceView(this));  
           
     }  
 }  

@SurfaceViewDemoActivity.java

[java]  view plain copy  
 print ? 
 /* 
  * author: conowen 
  * e-mail: conowen@hotmail.com 
  * date  :  2012.8.4 
  */  
 package com.conowen.SurfaceViewDemo;  
   
 import android.content.Context;  
 import android.graphics.Canvas;  
 import android.graphics.Color;  
 import android.graphics.Paint;  
 import android.graphics.Rect;  
 import android.util.Log;  
 import android.view.SurfaceHolder;  
 import android.view.SurfaceView;  
   
 public class MySurfaceView extends SurfaceView implements  
         SurfaceHolder.Callback {  
   
     private String TAG = "conowen";  
       
     private SurfaceHolder sfh;  
     private boolean ThreadFlag;  
     private int counter;  
     private Canvas canvas;  
   
     private Thread mThread = new Thread(new Runnable() {  
   
         @Override  
         public void run() {  
             // TODO Auto-generated method stub  
             while (ThreadFlag) {  
   
                 // 锁定画布，得到Canvas对象  
                 canvas = sfh.lockCanvas();  
   
                 // 设定Canvas对象的背景颜色  
                 canvas.drawColor(Color.GREEN);  
   
                 // 创建画笔  
                 Paint p = new Paint();  
                 // 设置画笔颜色  
                 p.setColor(Color.RED);  
                 // 设置文字大小  
                 p.setTextSize(40);  
   
                 // 创建一个Rect对象rect  
                 // public Rect (int left, int top, int right, int bottom)  
                 Rect rect = new Rect(100, 50, 400, 350);  
                 // 在canvas上绘制rect  
                 canvas.drawRect(rect, p);  
                 // 在canvas上显示时间  
                 // public void drawText (String text, float x, float y, Paint  
                 // paint)  
                 canvas.drawText("时间 = " + (counter++) + " 秒", 500, 200, p);  
   
                 if (canvas != null) {  
                     // 解除锁定，并提交修改内容，更新屏幕  
                     sfh.unlockCanvasAndPost(canvas);  
                 }  
                 try {  
                     Thread.sleep(1000);  
                 } catch (InterruptedException e) {  
                     // TODO Auto-generated catch block  
                     e.printStackTrace();  
                 }  
             }  
         }  
   
     });  
   
     public MySurfaceView(Context context) {  
         super(context);  
         // TODO Auto-generated constructor stub  
   
         // 通过SurfaceView获得SurfaceHolder对象  
         sfh = this.getHolder();  
   
         // 为SurfaceHolder添加回调结构SurfaceHolder.Callback  
         sfh.addCallback(this);  
   
     }  
   
     @Override  
     public void surfaceChanged(SurfaceHolder holder, int format, int width,  
             int height) {  
         // TODO Auto-generated method stub  
         Log.i(TAG, "surfaceChanged");  
   
     }  
   
     @Override  
     public void surfaceCreated(SurfaceHolder holder) {  
         // TODO Auto-generated method stub  
         Log.i(TAG, "surfaceCreated");  
         counter = 0;  
         ThreadFlag = true;  
         mThread.start();  
   
     }  
   
     @Override  
     public void surfaceDestroyed(SurfaceHolder holder) {  
         // TODO Auto-generated method stub  
         Log.i(TAG, "surfaceDestroyed");  
         ThreadFlag = false;  
   
     }  
   
 }  
 
  