Camera API

 

public class

Camera

extendsObject

    本类主要用于和camera service建立及断开连接、设置拍照功能、开启及关闭预览、拍照、检索frames编码成video。本类没有默认的构造函数，你可以通过open()函数获得一个Camera对象。

       首先要使用硬件camera，必须要在manifest文件中声明使用权限，例如应用中要使用camera及自动对焦功能，那么manifest文件中包含下列几行声明：

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

   通过该类实现照相功能，一般需要下列几个步骤:

1通过函数open(int) 获得一个camera对象

2通过函数getParameters()得到一个已有的(默认的)设置

3 如果有需要，可以通过函数setParameters(Camera.Parameters)，修改第二步返回的Camera.Parameters对象.

4 通过函数setDisplayOrientation(int)来设置屏幕的水平或垂直

5 重要：传递一个已经初始化好了的SurfaceHolder对象给函数setPreviewDisplay(SurfaceHolder)，如果没有surface，carema是无法打开预览功能。

6 重要:调用函数startPreview()更新预览的surface，开始照相之前必须开启预览功能

7 通过函数ltakePicture(Camera.ShutterCallback, Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)实现照相功能.在回调函数中可以得到实际的相片数据.

8        每完成一次照相，预览功能会停止。如果要照更多像，需要再次调用startPreview() .

9 调用stopPreview()停止预览.

10 重要:调用release()以便其他应用可以方便使用camera.使用camera的应用程序应该在onPause()(并且在onResume()中重新re-open()),立即释放camera.

按照以下步骤快速切换video recording模式:

1        如上所述得到一个初始化的Camera，并开启预览功能.

2        调用unlock()使得media进程可以访问camera.

3        将camera传递给函数setCamera(Camera).查看关于video recording的MediaRecorder信息.

4        完成了recording，调用reconnect()来re-acquire and re-lock the camera.

5        如果有需要，可以重新开启预览，照更多的相、录更多视频.

6        最后如上所述调用函数stopPreview()andrelease()来停止预览.

     这个类不是线程安全的，这意味着是通过event thread使用该类。在绝大多数需要长时间运行的操作(预览、聚焦、照相等)都是非同步的，只要有需求就会立刻唤醒相关回调函数。而这些回调函数是由调用 open(int)的event thread来调用的。故这些类方法一定不能同时在多个线程中运行。

      注意：不同性能的android设备有不同的硬件规格，如兆像素等级和自动对焦性能，为了使你的应用和更多设备兼容，最好不要限制camera规格。

Public Methods
public final void addCallbackBuffer (byte[] callbackBuffer)
Since: API Level 8
    给callback buffer queue添加一个已分配好内存的buffer。应用程序可以添加一个或多个buffers到该队列中. 当一个preview frame产生并且该队列还有至少一个可用的buffer，那么该buffer将被移除队列使用。这时会唤醒preview callback。如果preview frame产生但是该队列中没有可用的buffer，那么这个frame就会被丢弃。应用程序应该在处理完buffer中数据后，再将buffer重新添加进队列。
    Buffer的大小是由该preview image的宽，高，及每个像素的bytes三者的乘积来决定的. 通过函数getPreviewSize()来得到该preview image的 width and height.通过函数getBitsPerPixel(int) / 8可以得到每个像素包含的 Bytes ,通过函数getPreviewFormat() 可以得到该image采用的格式.
    只有通过函数setPreviewCallbackWithBuffer(PreviewCallback)设置预览回调的时候，才会用到本函数。当通过函数setPreviewCallback(PreviewCallback) 或setOneShotPreviewCallback(PreviewCallback)设置预览回调时,所需的buffer由系统自动分配。
Parameters
callbackBuffer，添加到队列中的buffer。该buffer的大小应该是width * height * bits_per_pixel / 8.

public final voidautoFocus(Camera.AutoFocusCallback cb)

Since: API Level 1

打开camera的自动对焦功能并且注册一个当camera对焦时的回调函数。这个函数只在preview激活的时候有效(即在startPreview()and before stopPreview()之间。

调用者应该通过函数getFocusMode()来查看是否可以使用autoFocus()函数，如果camera并不支持auto-focus,那么该函数不做任何处理，立即调用onAutoFocus(Boolean ,Camera)函数。如果你的应用不能安装在没有自动对焦的设备上，你需要在你的应用程序中通过<uses-feature>manifest元素声明需要使用自动对焦功能。

如果当前的flash mode不是FLASH_MODE_OFF，flash将在自动对焦过程中启动，具体依赖于驱动及camera硬件。

public final voidcancelAutoFocus()

Since: API Level 5

取消任何当前正在运行的auto-focus.该方法将focus position重置为默认的值。如果camera不支持auto-focus，该方法不做任何操作。

See Also

autoFocus(Camera.AutoFocusCallback)

public static voidgetCameraInfo(int cameraId,Camera.CameraInfo cameraInfo)

Since: API Level 9

返回某一特定camera的信息

如果getNumberOfCameras()返回N，有效id从0到N-1。

public static intgetNumberOfCameras()

Since: API Level 9

返回本设备上的所有可用的物理camera个数

publicCamera.ParametersgetParameters()

Since: API Level 1

返回当前Camera service的设置，如果要修改参数，必须将返回的Parameters对象传递给函数setParameters(Camera.Parameters)实现.

See Also

setParameters(Camera.Parameters)

public final voidlock()

Since: API Level 5

Re-locks the camera to prevent other processes from accessing it. Camera objects are locked by default unlessunlock()is called. Normally reconnect()is used instead.

If you are not recording video, you probably do not need this method.

给camera加锁以防止其他进程的访问，默认情况下camera是被锁的，除非调用unlock()函数解锁。通常可以通过函数reconnect()代替。如果你不需要recording viedo功能，你不需要使用该方法。

Throws

RuntimeException

if the camera cannot be  re-locked (for example, if the camera is still in use by another process).

public staticCameraopen(int cameraId)

Since: API Level 9

创建一个新的camera对象以使用camera硬件

当你使用了camera后，一定要调用release(),否则camera将被一直锁住，无法被其他应用程序使用。

应用程序同时只能存在一个激活的camera

其他方法的callback函数会传递给调用open()函数的线程的event loop。如果该线程没有event loop，那么回调函数就会被传递给main application event loop，如果没有main application event loop，callback函数不会传递

注意:在一些设备上，该方法会运行很长一段时间，最好是在一个worker线程上调用该函数（(possibly usingAsyncTask）以避免阻塞main application UI thread.

Parameters

cameraId

the hardware camera to  access, between 0 andgetNumberOfCameras()-1.

Returns

返回一个connected locked并ready for use的Camera objecte.

Throws

RuntimeException

if connection to the  camera service fails (for example, if the camera is in use by another  process).

public staticCameraopen()

Since: API Level 1

创建一个新的访问设备上第一个back-facing camera的Camera类对象，如果设备没有back-facing camera，则该函数返回null。

See Also

open(int)

public final voidreconnect()

Since: API Level 8

在另一个进程使用之后，重新与camera建立连接。进程unlock()之后，该进程可能仍在使用camera(这里理解不知是否恰当)，当其使用完毕后，你一定要与camera重新建立连接，这样可重新获得锁以继续使用camera。

如果调用了setCamera(Camera)，该接口一定要在MediaRecorder之后调用。

当然如果你不需要使用recording video，你不用使用该函数

Throws

IOException

if a connection cannot  be re-established (for example, if the camera is still in use by another  process).

public final voidrelease()

Since: API Level 1

断开和释放Camera对象资源，当使用完了camera，你要尽快调用该函数。

public final voidsetDisplayOrientation(int degrees)

Since: API Level 8

设置preview的顺时针旋转角度。这将影响preview frames和拍照之后的相片显示。该方法主要用于垂直模式的应用。注意在旋转之前，front-facing cameras的preview显示是水平flip的，这就是说，image是沿着camera sensor的垂直中心轴来反射的（无法理解其意思）。所以用户可以像照镜子一样看到他们自己。这不会影响传入函数onPreviewFrame(byte[], Camera)的、JPEG相片的、或记录的video的byte array的顺序。在preview期间是不允许调用该方法的。如果你想要是你的照片和显示出来的角度一致，你可以参考下列代码：

publicstaticvoidsetCameraDisplayOrientation(Activity activity,
         int cameraId, android.hardware.Camera camera){
     android.hardware.Camera.CameraInfo info =
             new android.hardware.Camera.CameraInfo();
     android.hardware.Camera.getCameraInfo(cameraId, info);
     int rotation= activity.getWindowManager().getDefaultDisplay()
             .getRotation();
     int degrees=0;
     switch(rotation){
         caseSurface.ROTATION_0: degrees=0;break;
         caseSurface.ROTATION_90: degrees=90;break;
         caseSurface.ROTATION_180: degrees=180;break;
         caseSurface.ROTATION_270: degrees=270;break;
     }

     int result;
     if(info.facing==Camera.CameraInfo.CAMERA_FACING_FRONT){
         result =(info.orientation+ degrees)%360;
         result =(360- result)%360;// compensate the mirror
     }else{// back-facing
         result =(info.orientation- degrees +360)%360;
     }
     camera.setDisplayOrientation(result);
}

Parameters

degrees

the angle that the  picture will be rotated clockwise. Valid values are 0, 90, 180, and 270. The  starting position is 0 (landscape).

See Also

·    setPreviewDisplay(SurfaceHolder)

public final voidsetErrorCallback(Camera.ErrorCallback cb)

Since: API Level 1

Registers a callback to be invoked when an error occurs.

Parameters

cb	The callback to run

public final voidsetOneShotPreviewCallback(Camera.PreviewCallbackcb)

Since: API Level 3

Installs a callback to be invoked for the next preview frame in addition to displaying it on the screen.一次调用后，该回调函数就会被清除，该函数可在任何时候调用，即使是正在预览，调用该函数将覆盖以前的回调。

Parameters

cb	a callback object that  receives a copy of the next preview frame, or null to stop receiving  callbacks.

public voidsetParameters(Camera.Parametersparams)

Since: API Level 1

Changes the settings for this Camera service.

Parameters

params

the Parameters to use  for this Camera service

Throws

RuntimeException

if any parameter is  invalid or not supported.

See Also

·    getParameters()

public final voidsetPreviewCallback(Camera.PreviewCallbackcb)

Since: API Level 1

该函数为每个preview frame安装一个callback，并将每个preview frame显示到屏幕上，只要preview处在激活状态，这些回调函数就会被重复调用.该方法可以在任何时候调用，即使preview is live. 调用该函数将覆盖一起设置的其他的回调.

Parameters

cb	a callback object that  receives a copy of each preview frame, or null to stop receiving callbacks.

public final voidsetPreviewCallbackWithBuffer(Camera.PreviewCallbackcb)

Since: API Level 8

安装一个会被每个preview frame激活的回调函数，这些回调函数使用由addCallbackBuffer(byte[])提供的buffer，并将每个preview frame显示到屏幕上。只要preview是激活的buffer是足够的，这些回调就会不断重复被调用,并覆盖其他的回调。

该方法目的是要通过复用preview frame memory来提高preview的性能和帧率。在调用该方法前后或没有回调注册时，需要调用函数addCallbackBuffer(byte[]).如果传一个空的callback给该函数，那么buffer queue将被清除.将调用setPreviewCallback(Camera.PreviewCallback)或setOneShotPreviewCallback(Camera.PreviewCallback).

Parameters

cb	获得了preview frame数据拷贝的回调对象，如果cb为空，该函数将停止接受callbacks并清空buffer queue.

See Also

·    addCallbackBuffer(byte[])

public final voidsetPreviewDisplay(SurfaceHolderholder)

Since: API Level 1

为live preview设置surface，对于preview，surface是必要;对于拍照preview是必要的。相同的surface可以被无损重置。

在调用该方法时SurfaceHolder必须已经包含了一个surface.如果使用SurfaceView，必须通过函数addCallback(SurfaceHolder.Callback)注册一个SurfaceHolder.Callback并且在调用 setPreviewDisplay() 或开启preview.之前，等待surfaceCreated(SurfaceHolder)

在调用startPreview()函数之前，必须调用该函数。不过有一个例外，那就是如果调用startPreview()之前，没有设置preview surface或者设为null，该函数可能被传入一个非空parameter，调用一次已设置的preview surface(这就是得camera的启动和surface的创建可以并行，节省了时间)，在preview运行的时候，这个preview surface 不可更改。.

Parameters

holder

包含放置preview的surface，可能为空以移除原来的preview surface

Throws

IOException

if the method fails  (for example, if the surface is unavailable or unsuitable).

public final voidsetZoomChangeListener(Camera.OnZoomChangeListenerlistener)

Since: API Level 8

Registers a listener to be notified when the zoom value is updated by the camera driver during smooth zoom.

设置监听器监听smooth zoom期间，camera驱动对zoom value的值的更改

Parameters

listener

the listener to notify

See Also

·    startSmoothZoom(int)

public final voidstartPreview()

Since: API Level 1

开始捕捉和绘制preview frames到屏幕上。当然preveiw并没有真正开启，直到通过函数setPreviewDisplay(SurfaceHolder)得到a surface.

如果调用了setPreviewCallback(Camera.PreviewCallback),setOneShotPreviewCallback(Camera.PreviewCallback),或setPreviewCallbackWithBuffer(Camera.PreviewCallback) ,当框架发现preview data可用时会自动调用回调函数onPreviewFrame(byte[], Camera)。

public final voidstartSmoothZoom(int value)

Since: API Level 8

该函数使相机平滑变焦到value值.驱动会时时通知Camera.OnZoomChangeListener zoom值及是否已经停止变焦了.例如当前的zoom是0，设置value为3然后调用startSmoothZoom.那么函数onZoomChange(int, boolean, Camera)会被调用三次，分别传入zoom值为1, 2, and 3.应用程序也可以提前调用函数stopSmoothZoom()来停止变焦.在停止变焦之前，不能再次调用startSmoothZoom函数或更改zoom值.如果提供的目标zoom值和当前zoom值一致了，就不会在调用回调函数。通过函数isSmoothZoomSupported()测试硬件是否支持变焦，如果返回值为true，说明支持，则可以使用本函数实现变焦.

Parameters

value

zoom value. The valid  range is 0 to getMaxZoom().

Throws

IllegalArgumentException	if the zoom value is  invalid.
RuntimeException	if the method fails.

See Also

·    setZoomChangeListener(OnZoomChangeListener)

public final voidstopPreview()

Since: API Level 1

停止拍照，停止将预览帧绘制到surface上，并且重置camera，以备下次startPreview().

public final voidstopSmoothZoom()

Since: API Level 8

停止平稳变焦。应用程序可以设置Camera.OnZoomChangeListener监听器来监听zoom的停止.同样如果函数isSmoothZoomSupported()返回true，表示硬件支持变焦，可以调用本函数。.

Throws

RuntimeException

if the method fails.

public final voidtakePicture(Camera.ShutterCallbackshutter,Camera.PictureCallbackraw, Camera.PictureCallbackjpeg)

Since: API Level 1

与 takePicture(shutter, raw, null, jpeg)等效.

See Also

·    takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)

public final voidtakePicture(Camera.ShutterCallbackshutter,Camera.PictureCallbackraw, Camera.PictureCallbackpostview, Camera.PictureCallbackjpeg)

Since: API Level 5

触发一次非同步拍照，camera service将按照拍照的流程为应用完成一系列的回调初始化。 shutter callback，拍照之后会调用该回调.该函数中可以触发一个声音，提示用户拍照完成。 The raw callback occurs ，当raw image data有效的时候，会触发该回调 (注意:如果没有足够的memory用来放置拷贝，该值可能为). The postview callback ,当生成了经过缩放、简单处理的图片的时候，调用postview callback回调(注意：并不是所有的硬件都支持该功能)。The jpeg callback，当压缩的图片数据有效的时候，会调用该回到接口。对于这些参数，如果没有需要，可以直接传递null即可.

当然这些回调方法，都必须在preview是激活的(即在函数startPreview()调用之后).完成拍照之后，preview会停止，这个时候如果你想要再次开开preview，拍摄更多的照片，你需要重新调用startPreview().

.

Parameters

shutter	the callback for image  capture moment, or null
raw	the callback for raw  (uncompressed) image data, or null
postview	callback with postview  image data, may be null
jpeg	the callback for JPEG  image data, or null

public final voidunlock()

Since: API Level 5

为camera解锁，使得其他进程可以访问camera.一般地,直到调用函数release()，camera都是被包含激活的camera对象的进程锁住的.如果要在进程间快速还手,你可以调用该函数快速释放camera对象给其他进程使用;同样如果别的进程释放了camera，你可以调用函数reconnect()重新获取camera.

在调用setCamera(Camera).之前，你必须调用该函数。

如果你不使用recording video，可能你不需要用到该函数。

Throws

RuntimeException

if the camera cannot be  unlocked.