public class
Camera
extends Object
本類主要用於和 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 通過函數 l takePicture(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() and release() 來停止預覽 .
這個類不是線程安全的，這意味着是通過event thread使用該類。在絕大多數需要長時間運行的操作(預覽、聚焦、照相等)都是非同步的，只要有需求就會立刻喚醒相關回調函數。而這些回調函數是由調用 open(int)的event thread來調用的。故這些類方法一定不能同時在多個線程中運行。
注意：不同性能的android設備有不同的硬件規格，如兆像素等級和自動對焦性能，爲了使你的應用和更多設備兼容，最好不要限制camera規格。
P ublic 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 void autoFocus (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 void cancelAutoFocus ()
Since: API Level 5
取消任何當前正在運行的 auto-focus. 該方法將 focus position 重置爲默認的值。如果 camera 不支持 auto-focus ，該方法不做任何操作。
See Also
autoFocus(Camera.AutoFocusCallback)
public static void getCameraInfo (int cameraId, Camera.CameraInfo cameraInfo)
Since: API Level 9
返回某一特定 camera 的信息
如果 getNumberOfCameras() 返回 N ，有效 id 從 0 到 N-1 。
public static int getNumberOfCameras ()
Since: API Level 9
返回本設備上的所有可用的物理 camera 個數
public Camera.Parameters getParameters ()
Since: API Level 1
返回當前 Camera service 的設置，如果要修改參數，必須將返回的 Parameters 對象傳遞給函數setParameters(Camera.Parameters) 實現 .
See Also
setParameters(Camera.Parameters)
public final void lock ()
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
|
if the camera cannot be re-locked (for example, if the camera is still in use by another process). |
public static Camera open (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 using AsyncTask ）以避免阻塞 main application UI thread.
Parameters
|
cameraId |
the hardware camera to access, between 0 and getNumberOfCameras() -1. |
Returns
返回一個 connected locked 並 ready for use 的 Camera objecte.
Throws
|
if connection to the camera service fails (for example, if the camera is in use by another process). |
public static Camera open ()
Since: API Level 1
創建一個新的訪問設備上第一個 back-facing camera 的 Camera 類對象，如果設備沒有 back-facing camera ，則該函數返回 null 。
See Also
public final void reconnect ()
Since: API Level 8
在另一個進程使用之後，重新與 camera 建立連接。進程 unlock() 之後，該進程可能仍在使用 camera( 這裏理解不知是否恰當 ) ，當其使用完畢後，你一定要與 camera 重新建立連接，這樣可重新獲得鎖以繼續使用 camera 。
如果調用了 setCamera(Camera) ，該接口一定要在 MediaRecorder 之後調用。
當然如果你不需要使用 recording video ，你不用使用該函數
Throws
|
if a connection cannot be re-established (for example, if the camera is still in use by another process). |
public final void release ()
Since: API Level 1
斷開和釋放 Camera 對象資源，當使用完了 camera ，你要儘快調用該函數。
public final void setDisplayOrientation (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 期間是不允許調用該方法的。如果你想要是你的照片和顯示出來的角度一致，你可以參考下列代碼：
public static voidsetCameraDisplayOrientation ( Activityactivity ,
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 ) {
case Surface . ROTATION_0 :degrees = 0 ; break ;
case Surface . ROTATION_90 :degrees = 90 ; break ;
case Surface . ROTATION_180 :degrees = 180 ; break ;
case Surface . 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 void setErrorCallback (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 void setOneShotPreviewCallback (Camera.PreviewCallback cb)
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 void setParameters (Camera.Parameters params)
Since: API Level 1
Changes the settings for this Camera service.
Parameters
|
params |
the Parameters to use for this Camera service |
Throws
|
if any parameter is invalid or not supported. |
See Also
public final void setPreviewCallback (Camera.PreviewCallback cb)
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 void setPreviewCallbackWithBuffer (Camera.PreviewCallback cb)
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
public final void setPreviewDisplay (SurfaceHolder holder)
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
|
if the method fails (for example, if the surface is unavailable or unsuitable). |
public final void setZoomChangeListener (Camera.OnZoomChangeListener listener)
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
public final void startPreview ()
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 void startSmoothZoom (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
|
if the zoom value is invalid. |
|
|
if the method fails. |
See Also
· setZoomChangeListener(OnZoomChangeListener)
public final void stopPreview ()
Since: API Level 1
停止拍照，停止將預覽幀繪製到 surface 上，並且重置 camera ，以備下次 startPreview() .
public final void stopSmoothZoom ()
Since: API Level 8
停止平穩變焦。應用程序可以設置 Camera.OnZoomChangeListener 監聽器來監聽 zoom 的停止 . 同樣如果函數 isSmoothZoomSupported() 返回 true ，表示硬件支持變焦，可以調用本函數。 .
Throws
|
if the method fails. |
public final void takePicture (Camera.ShutterCallback shutter, Camera.PictureCallback raw, Camera.PictureCallbackjpeg)
Since: API Level 1
與 takePicture(shutter, raw, null, jpeg) 等效 .
See Also
· takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)
public final void takePicture (Camera.ShutterCallback shutter, Camera.PictureCallback raw, Camera.PictureCallbackpostview, Camera.PictureCallback jpeg)
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 void unlock ()
Since: API Level 5
爲 camera 解鎖，使得其他進程可以訪問 camera. 一般地 , 直到調用函數 release() ， camera 都是被包含激活的camera 對象的進程鎖住的 . 如果要在進程間快速還手 , 你可以調用該函數快速釋放 camera 對象給其他進程使用 ; 同樣如果別的進程釋放了 camera ，你可以調用函數 reconnect() 重新獲取 camera.
在調用 setCamera(Camera) . 之前，你必須調用該函數。
如果你不使用 recording video ，可能你不需要用到該函數。
Throws
|
if the camera cannot be unlocked. |
