<uses-feature android:name="android.hardware.camera" />-
For a list of camera features, see the manifest Features
+ For a list of camera features, see the manifest
+Features
Reference. Adding camera features to your manifest causes Android Market to prevent your application from
being installed to devices that do not include a camera or do not support the camera features you
@@ -148,6 +156,15 @@ application must request the audio capture permission.
<uses-permission android:name="android.permission.RECORD_AUDIO" />
+ For more information about getting user location, see
+Obtaining User
+Location.
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+
Camera hardware is a shared resource that must be carefully managed so your application does not collide with other applications that may also want to use it. The following sections discusses -how to detect camera hardware, how to request access to a camera and how to release it when your -application is done using it.
+how to detect camera hardware, how to request access to a camera, how to capture pictures or video +and how to release the camera when your application is done using it.Caution: Remember to release the {@link android.hardware.Camera} object by calling the {@link android.hardware.Camera#release() Camera.release()} when your @@ -492,7 +509,8 @@ public class CameraPreview extends SurfaceView implements SurfaceHolder.Callback // ignore: tried to stop a non-existent preview } - // make any resize, rotate or reformatting changes here + // set preview size and make any resize, rotate or + // reformatting changes here // start preview with new settings try { @@ -506,6 +524,12 @@ public class CameraPreview extends SurfaceView implements SurfaceHolder.Callback } +
If you want to set a specific size for your camera preview, set this in the {@code +surfaceChanged()} method as noted in the comments above. When setting preview size, you +must use values from {@link android.hardware.Camera.Parameters#getSupportedPreviewSizes}. +Do not set arbitrary values in the {@link +android.hardware.Camera.Parameters#setPreviewSize setPreviewSize()} method.
+A camera preview class, such as the example shown in the previous section, must be placed in the @@ -780,6 +804,10 @@ without creating a camera preview first and skip the first few steps of this pro since users typically prefer to see a preview before starting a recording, that process is not discussed here.
+Tip: If your application is typically used for recording video, set +{@link android.hardware.Camera.Parameters#setRecordingHint} to {@code true} prior to starting your +preview. This setting can help reduce the time it takes to start recording.
+When using the {@link android.media.MediaRecorder} class to record video, you must perform configuration steps in a specific order and then call the {@link @@ -851,7 +879,7 @@ setAudioChannels()}
When starting and stopping video recording using the {@link android.media.MediaRecorder} class, you must follow a specific order, as listed below.
@@ -938,7 +966,7 @@ public class CameraActivity extends Activity { private MediaRecorder mMediaRecorder; ... - + @Override protected void onPause() { super.onPause(); @@ -1052,4 +1080,425 @@ instead. For more information, see Saving Shared Files.For more information about saving files on an Android device, see Data Storage.
\ No newline at end of file +href="{@docRoot}guide/topics/data/data-storage.html">Data Storage. + + +Android supports a wide array of camera features you can control with your camera application, +such as picture format, flash mode, focus settings, and many more. This section lists the common +camera features, and briefly discusses how to use them. Most camera features can be accessed and set +using the through {@link android.hardware.Camera.Parameters} object. However, there are several +important features that require more than simple settings in {@link +android.hardware.Camera.Parameters}. These features are covered in the following sections:
+ +
+ +For general information about how to use features that are controlled through {@link +android.hardware.Camera.Parameters}, review the Using camera +features section. For more detailed information about how to use features controlled through the +camera parameters object, follow the links in the feature list below to the API reference +documentation.
+ ++ Table 1. Common camera features sorted by the Android API Level in which they +were introduced.
+| Feature | API Level | Description | +
|---|---|---|
| Face Detection | +14 | +Identify human faces within a picture and use them for focus, metering and white +balance | +
| Metering Areas | +14 | +Specify one or more areas within an image for calculating white balance | +
| Focus Areas | +14 | +Set one or more areas within an image to use for focus | +
| {@link android.hardware.Camera.Parameters#setAutoWhiteBalanceLock White Balance Lock} | +14 | +Stop or start automatic white balance adjustments | +
| {@link android.hardware.Camera.Parameters#setAutoExposureLock Exposure Lock} | +14 | +Stop or start automatic exposure adjustments | +
| {@link android.hardware.Camera#takePicture Video Snapshot} | +14 | +Take a picture while shooting video (frame grab) | +
| Time Lapse Video | +11 | +Record frames with set delays to record a time lapse video | +
| {@link android.hardware.Camera#open(int) Multiple Cameras} | +9 | +Support for more than one camera on a device, including front-facing and back-facing +cameras | +
| {@link android.hardware.Camera.Parameters#getFocusDistances Focus Distance} | +9 | +Reports distances between the camera and objects that appear to be in focus | +
| {@link android.hardware.Camera.Parameters#setZoom Zoom} | +8 | +Set image magnification | +
| {@link android.hardware.Camera.Parameters#setExposureCompensation Exposure +Compensation} | +8 | +Increase or decrease the light exposure level | +
| {@link android.hardware.Camera.Parameters#setGpsLatitude GPS Data} | +5 | +Include or omit geographic location data with the image | +
| {@link android.hardware.Camera.Parameters#setWhiteBalance White Balance} | +5 | +Set the white balance mode, which affects color values in the captured image | +
| {@link android.hardware.Camera.Parameters#setFocusMode Focus Mode} | +5 | +Set how the camera focuses on a subject such as automatic, fixed, macro or infinity | +
| {@link android.hardware.Camera.Parameters#setSceneMode Scene Mode} | +5 | +Apply a preset mode for specific types of photography situations such as night, beach, snow +or candlelight scenes | +
| {@link android.hardware.Camera.Parameters#setJpegQuality JPEG Quality} | +5 | +Set the compression level for a JPEG image, which increases or decreases image output file +quality and size | +
| {@link android.hardware.Camera.Parameters#setFlashMode Flash Mode} | +5 | +Turn flash on, off, or use automatic setting | +
| {@link android.hardware.Camera.Parameters#setColorEffect Color Effects} | +5 | +Apply a color effect to the captured image such as black and white, sepia tone or negative. + | +
| {@link android.hardware.Camera.Parameters#setAntibanding Anti-Banding} | +5 | +Reduces the effect of banding in color gradients due to JPEG compression | +
| {@link android.hardware.Camera.Parameters#setPictureFormat Picture Format} | +1 | +Specify the file format for the picture | +
| {@link android.hardware.Camera.Parameters#setPictureSize Picture Size} | +1 | +Specify the pixel dimensions of the saved picture | +
Note: These features are not supported on all devices due to +hardware differences and software implementation. For information on checking the availability +of features on the device where your application is running, see Checking +feature availability.
+ + +The first thing to understand when setting out to use camera features on Android devices is that +not all camera features are supported on all devices. In addition, devices that support a particular +feature may support them to different levels or with different options. Therefore, part of your +decision process as you develop a camera application is to decide what camera features you want to +support and to what level. After making that decision, you should plan on including code in your +camera application that checks to see if device hardware supports those features and fails +gracefully if a feature is not available.
+ +You can check the availabilty of camera features by getting an instance of a camera’s parameters +object, and checking the relevant methods. The following code sample shows you how to obtain a +{@link android.hardware.Camera.Parameters} object and check if the camera supports the autofocus +feature:
+ +
+// get Camera parameters
+Camera.Parameters params = mCamera.getParameters();
+
+List<String> focusModes = params.getSupportedFocusModes();
+if (focusModes.contains(Camera.Parameters.FOCUS_MODE_AUTO)) {
+ // Autofocus mode is supported
+}
+
+
+You can use the technique shown above for most camera features. The +{@link android.hardware.Camera.Parameters} object provides a {@code getSupported...()}, {@code +is...Supported()} or {@code getMax...()} method to determine if (and to what extent) a feature is +supported.
+ +If your application requires certain camera features in order to function properly, you can +require them through additions to your application manifest. When you declare the use of specific +camera features, such as flash and auto-focus, the Android Market restricts your application from +being installed on devices which do not support these features. For a list of camera features that +can be declared in your app manifest, see the manifest + Features +Reference.
+ +Most camera features are activated and controlled using a {@link +android.hardware.Camera.Parameters} object. You obtain this object by first getting an instance of +the {@link android.hardware.Camera} object, calling the {@link +android.hardware.Camera#getParameters getParameters()} method, changing the returned parameter +object and then setting it back into the camera object, as demonstrated in the following example +code:
+ ++// get Camera parameters +Camera.Parameters params = mCamera.getParameters(); +// set the focus mode +params.setFocusMode(Camera.Parameters.FOCUS_MODE_AUTO); +// set Camera parameters +mCamera.setParameters(params); ++ +
This technique works for nearly all camera features, and most parameters can be changed at any +time after you have obtained an instance of the {@link android.hardware.Camera} object. Changes to +parameters are typically visible to the user immediately in the application’s camera preview. +On the software side, parameter changes may take several frames to actually take effect as the +camera hardware processes the new instructions and then sends updated image data.
+ +Important: Some camera features cannot be changed at will. In +particular, changing the size or orientation of the camera preview requires that you first stop the +preview, change the preview size, and then restart the preview. Starting with Android 4.0 (API +Level 14) preview orientation can be changed without restarting the preview.
+ +Other camera features require more code in order to implement, including:
+A quick outline of how to implement these features is provided in the following sections.
+ + +In some photographic scenarios, automatic focusing and light metering may not produce the +desired results. Starting with Android 4.0 (API Level 14), your camera application can provide +additional controls to allow your app or users to specify areas in an image to use for determining +focus or light level settings and pass these values to the camera hardware for use in capturing +images or video.
+ +Areas for metering and focus work very similarly to other camera features, in that you control +them through methods in the {@link android.hardware.Camera.Parameters} object. The following code +demonstrates setting two light metering areas for an instance of +{@link android.hardware.Camera}:
+ +
+// Create an instance of Camera
+mCamera = getCameraInstance();
+
+// set Camera parameters
+Camera.Parameters params = mCamera.getParameters();
+
+if (params.getMaxNumMeteringAreas() > 0){ // check that metering areas are supported
+ List<Camera.Area> meteringAreas = new ArrayList<Camera.Area>();
+
+ Rect areaRect1 = new Rect(-100, -100, 100, 100); // specify an area in center of image
+ meteringAreas.add(new Camera.Area(areaRect1, 600)); // set weight to 60%
+ Rect areaRect2 = new Rect(800, -1000, 1000, -800); // specify an area in upper right of image
+ meteringAreas.add(new Camera.Area(areaRect2, 400)); // set weight to 40%
+ params.setMeteringAreas(meteringAreas);
+}
+
+mCamera.setParameters(params);
+
+
+The {@link android.hardware.Camera.Area} object contains two data parameters: A {@link +android.graphics.Rect} object for specifying an area within the camera’s field of view and a weight +value, which tells the camera what level of importance this area should be given in light metering +or focus calculations.
+ +The {@link android.graphics.Rect} field in a {@link android.hardware.Camera.Area} object +describes a rectangular shape mapped on a 2000 x 2000 unit grid. The coordinates -1000, -1000 +represent the top, left corner of the camera image, and coordinates 1000, 1000 represent the +bottom, right corner of the camera image, as shown in the illustration below.
+ +
++ Figure 1. The red lines illustrate the coordinate system for specifying a +{@link android.hardware.Camera.Area} within a camera preview. The blue box shows the location and +shape of an camera area with the {@link android.graphics.Rect} values 333,333,667,667. +
+ +The bounds of this coordinate system always correspond to the outer edge of the image visible in +the camera preview and do not shrink or expand with the zoom level. Similarly, rotation of the image +preview using {@link android.hardware.Camera#setDisplayOrientation Camera.setDisplayOrientation()} +does not remap the coordinate system.
+ + +For pictures that include people, faces are usually the most important part of the picture, and +should be used for determining both focus and white balance when capturing an image. The Android 4.0 +(API Level 14) framework provides APIs for identifying faces and calculating picture settings using +face recognition technology.
+ +Note: While the face detection feature is running, +{@link android.hardware.Camera.Parameters#setWhiteBalance}, +{@link android.hardware.Camera.Parameters#setFocusAreas} and +{@link android.hardware.Camera.Parameters#setMeteringAreas} have no effect.
+ +Using the face detection feature in your camera application requires a few general steps:
+The face detection feature is not supported on all devices. You can check that this feature is +supported by calling {@link android.hardware.Camera.Parameters#getMaxNumDetectedFaces}. An +example of this check is shown in the {@code startFaceDetection()} sample method below.
+ +In order to be notified and respond to the detection of a face, your camera application must set +a listener for face detection events. In order to do this, you must create a listener class that +implements the {@link android.hardware.Camera.FaceDetectionListener} interface as shown in the +example code below.
+ +
+class MyFaceDetectionListener implements Camera.FaceDetectionListener {
+
+ @Override
+ public void onFaceDetection(Face[] faces, Camera camera) {
+ if (faces.length > 0){
+ Log.d("FaceDetection", "face detected: "+ faces.length +
+ " Face 1 Location X: " + faces[0].rect.centerX() +
+ "Y: " + faces[0].rect.centerY() );
+ }
+ }
+}
+
+
+After creating this class, you then set it into your application’s +{@link android.hardware.Camera} object, as shown in the example code below:
+ ++mCamera.setFaceDetectionListener(new MyFaceDetectionListener()); ++ +
Your application must start the face detection function each time you start (or restart) the +camera preview. Create a method for starting face detection so you can call it as needed, as shown +in the example code below.
+ +
+public void startFaceDetection(){
+ // Try starting Face Detection
+ Camera.Parameters params = mCamera.getParameters();
+
+ // start face detection only *after* preview has started
+ if (params.getMaxNumDetectedFaces() > 0){
+ // camera supports face detection, so can start it:
+ mCamera.startFaceDetection();
+ }
+}
+
+
+You must start face detection each time you start (or restart) the camera preview. If +you use the preview class shown in Creating a preview class, add your +{@link android.hardware.Camera#startFaceDetection startFaceDetection()} method to both the +{@link android.view.SurfaceHolder.Callback#surfaceCreated surfaceCreated()} and {@link +android.view.SurfaceHolder.Callback#surfaceChanged surfaceChanged()} methods in your preview class, +as shown in the sample code below.
+ +
+public void surfaceCreated(SurfaceHolder holder) {
+ try {
+ mCamera.setPreviewDisplay(holder);
+ mCamera.startPreview();
+
+ startFaceDetection(); // start face detection feature
+
+ } catch (IOException e) {
+ Log.d(TAG, "Error setting camera preview: " + e.getMessage());
+ }
+}
+
+public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
+
+ if (mHolder.getSurface() == null){
+ // preview surface does not exist
+ Log.d(TAG, "mHolder.getSurface() == null");
+ return;
+ }
+
+ try {
+ mCamera.stopPreview();
+
+ } catch (Exception e){
+ // ignore: tried to stop a non-existent preview
+ Log.d(TAG, "Error stopping camera preview: " + e.getMessage());
+ }
+
+ try {
+ mCamera.setPreviewDisplay(mHolder);
+ mCamera.startPreview();
+
+ startFaceDetection(); // re-start face detection feature
+
+ } catch (Exception e){
+ // ignore: tried to stop a non-existent preview
+ Log.d(TAG, "Error starting camera preview: " + e.getMessage());
+ }
+}
+
+
+Note: Remember to call this method after calling +{@link android.hardware.Camera#startPreview startPreview()}. Do not attempt to start face detection +in the {@link android.app.Activity#onCreate onCreate()} method of your camera app’s main activity, +as the preview is not available by this point in your application's the execution.
+ + +Time lapse video allows users to create video clips that combine pictures taken a few seconds or +minutes apart. This feature uses {@link android.media.MediaRecorder} to record the images for a time +lapse sequence.
+ +To record a time lapse video with {@link android.media.MediaRecorder}, you must configure the +recorder object as if you are recording a normal video, setting the captured frames per second to a +low number and using one of the time lapse quality settings, as shown in the code example below.
+ ++// Step 3: Set a CamcorderProfile (requires API Level 8 or higher) +mMediaRecorder.setProfile(CamcorderProfile.get(CamcorderProfile.QUALITY_TIME_LAPSE_HIGH)); +... +// Step 5.5: Set the video capture rate to a low number +mMediaRecorder.setCaptureRate(0.1); // capture a frame every 10 seconds ++ +
These settings must be done as part of a larger configuration procedure for {@link +android.media.MediaRecorder}. For a full configuration code example, see Configuring MediaRecorder. Once the configuration is complete, +you start the video recording as if you were recording a normal video clip. For more information +about configuring and running {@link android.media.MediaRecorder}, see Capturing videos.
diff --git a/docs/html/guide/topics/media/images/camera-area-coordinates.png b/docs/html/guide/topics/media/images/camera-area-coordinates.png new file mode 100644 index 0000000000000..9876453921c83 Binary files /dev/null and b/docs/html/guide/topics/media/images/camera-area-coordinates.png differ diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd index 7c1754feb94f5..0e0412a10d526 100644 --- a/docs/html/guide/topics/media/index.jd +++ b/docs/html/guide/topics/media/index.jd @@ -6,7 +6,7 @@ page.title=Multimedia and Camera