1 /*
2  * Copyright (C) 2012 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ANDROID_SERVERS_CAMERA_CAMERA2PARAMETERS_H
18 #define ANDROID_SERVERS_CAMERA_CAMERA2PARAMETERS_H
19 
20 #include <system/graphics.h>
21 
22 #include <utils/Compat.h>
23 #include <utils/Errors.h>
24 #include <utils/KeyedVector.h>
25 #include <utils/Mutex.h>
26 #include <utils/String8.h>
27 #include <utils/Vector.h>
28 
29 #include <camera/CameraParameters.h>
30 #include <camera/CameraParameters2.h>
31 #include <camera/CameraMetadata.h>
32 
33 #include "common/CameraDeviceBase.h"
34 
35 namespace android {
36 namespace camera2 {
37 
38 /**
39  * Current camera state; this is the full state of the Camera under the old
40  * camera API (contents of the CameraParameters2 object in a more-efficient
41  * format, plus other state). The enum values are mostly based off the
42  * corresponding camera2 enums, not the camera1 strings. A few are defined here
43  * if they don't cleanly map to camera2 values.
44  */
45 struct Parameters {
46     /**
47      * Parameters and other state
48      */
49     int cameraId;
50     int cameraFacing;
51 
52     int previewWidth, previewHeight;
53     int32_t previewFpsRange[2];
54     int previewFormat;
55 
56     int previewTransform; // set by CAMERA_CMD_SET_DISPLAY_ORIENTATION
57 
58     int pictureWidth, pictureHeight;
59     // Store the picture size before they are overriden by video snapshot
60     int pictureWidthLastSet, pictureHeightLastSet;
61     bool pictureSizeOverriden;
62 
63     int32_t jpegThumbSize[2];
64     uint8_t jpegQuality, jpegThumbQuality;
65     int32_t jpegRotation;
66 
67     bool gpsEnabled;
68     double gpsCoordinates[3];
69     int64_t gpsTimestamp;
70     String8 gpsProcessingMethod;
71 
72     uint8_t wbMode;
73     uint8_t effectMode;
74     uint8_t antibandingMode;
75     uint8_t sceneMode;
76 
77     enum flashMode_t {
78         FLASH_MODE_OFF = 0,
79         FLASH_MODE_AUTO,
80         FLASH_MODE_ON,
81         FLASH_MODE_TORCH,
82         FLASH_MODE_RED_EYE = ANDROID_CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE,
83         FLASH_MODE_INVALID = -1
84     } flashMode;
85 
86     enum focusMode_t {
87         FOCUS_MODE_AUTO = ANDROID_CONTROL_AF_MODE_AUTO,
88         FOCUS_MODE_MACRO = ANDROID_CONTROL_AF_MODE_MACRO,
89         FOCUS_MODE_CONTINUOUS_VIDEO = ANDROID_CONTROL_AF_MODE_CONTINUOUS_VIDEO,
90         FOCUS_MODE_CONTINUOUS_PICTURE = ANDROID_CONTROL_AF_MODE_CONTINUOUS_PICTURE,
91         FOCUS_MODE_EDOF = ANDROID_CONTROL_AF_MODE_EDOF,
92         FOCUS_MODE_INFINITY,
93         FOCUS_MODE_FIXED,
94         FOCUS_MODE_INVALID = -1
95     } focusMode;
96 
97     uint8_t focusState; // Latest focus state from HAL
98 
99     // For use with triggerAfWithAuto quirk
100     focusMode_t shadowFocusMode;
101 
102     struct Area {
103         int left, top, right, bottom;
104         int weight;
AreaParameters::Area105         Area() {}
AreaParameters::Area106         Area(int left, int top, int right, int bottom, int weight):
107                 left(left), top(top), right(right), bottom(bottom),
108                 weight(weight) {}
isEmptyParameters::Area109         bool isEmpty() const {
110             return (left == 0) && (top == 0) && (right == 0) && (bottom == 0);
111         }
112     };
113     Vector<Area> focusingAreas;
114 
115     struct Size {
116         int32_t width;
117         int32_t height;
118     };
119 
120     struct FpsRange {
121         int32_t low;
122         int32_t high;
123     };
124 
125     uint8_t aeState; //latest AE state from Hal
126     int32_t exposureCompensation;
127     bool autoExposureLock;
128     bool autoExposureLockAvailable;
129     bool autoWhiteBalanceLock;
130     bool autoWhiteBalanceLockAvailable;
131 
132     // 3A region types, for use with ANDROID_CONTROL_MAX_REGIONS
133     enum region_t {
134         REGION_AE = 0,
135         REGION_AWB,
136         REGION_AF,
137         NUM_REGION // Number of region types
138     } region;
139 
140     Vector<Area> meteringAreas;
141 
142     int zoom;
143     bool zoomAvailable;
144 
145     int videoWidth, videoHeight, videoFormat;
146     android_dataspace videoDataSpace;
147 
148     bool recordingHint;
149     bool videoStabilization;
150 
151     CameraParameters2 params;
152     String8 paramsFlattened;
153 
154     // These parameters are also part of the camera API-visible state, but not
155     // directly listed in Camera.Parameters
156     // One of ICamera::VIDEO_BUFFER_MODE_*
157     int32_t videoBufferMode;
158     bool playShutterSound;
159     bool enableFaceDetect;
160 
161     bool enableFocusMoveMessages;
162     int afTriggerCounter;
163     int afStateCounter;
164     int currentAfTriggerId;
165     bool afInMotion;
166 
167     int precaptureTriggerCounter;
168 
169     int takePictureCounter;
170 
171     uint32_t previewCallbackFlags;
172     bool previewCallbackOneShot;
173     bool previewCallbackSurface;
174 
175     bool allowZslMode;
176     // Whether the jpeg stream is slower than 30FPS and can slow down preview.
177     // When slowJpegMode is true, allowZslMode must be false to avoid slowing down preview.
178     bool slowJpegMode;
179     // Whether ZSL reprocess is supported by the device.
180     bool isZslReprocessPresent;
181     // Whether the device supports enableZsl.
182     bool isDeviceZslSupported;
183     // Whether the device supports geometric distortion correction
184     bool isDistortionCorrectionSupported;
185 
186     // Overall camera state
187     enum State {
188         DISCONNECTED,
189         STOPPED,
190         WAITING_FOR_PREVIEW_WINDOW,
191         PREVIEW,
192         RECORD,
193         STILL_CAPTURE,
194         VIDEO_SNAPSHOT
195     } state;
196 
197     // Number of zoom steps to simulate
198     static const unsigned int NUM_ZOOM_STEPS = 100;
199     // Max preview size allowed
200     // This is set to a 1:1 value to allow for any aspect ratio that has
201     // a max long side of 1920 pixels
202     static const unsigned int MAX_PREVIEW_WIDTH = 1920;
203     static const unsigned int MAX_PREVIEW_HEIGHT = 1920;
204     // Initial max preview/recording size bound
205     static const int MAX_INITIAL_PREVIEW_WIDTH = 1920;
206     static const int MAX_INITIAL_PREVIEW_HEIGHT = 1080;
207     // Aspect ratio tolerance
208     static const CONSTEXPR float ASPECT_RATIO_TOLERANCE = 0.001;
209     // Threshold for slow jpeg mode
210     static const int64_t kSlowJpegModeThreshold = 33400000LL; // 33.4 ms
211     // Margin for checking FPS
212     static const int32_t FPS_MARGIN = 1;
213     // Max FPS for default parameters
214     static const int32_t MAX_DEFAULT_FPS = 30;
215     // Minimum FPS for a size to be listed in supported preview/video sizes
216     // Set to slightly less than 30.0 to have some tolerance margin
217     static constexpr double MIN_PREVIEW_RECORD_FPS = 29.97;
218     // Maximum frame duration for a size to be listed in supported preview/video sizes
219     static constexpr int64_t MAX_PREVIEW_RECORD_DURATION_NS = 1e9 / MIN_PREVIEW_RECORD_FPS;
220 
221     // Full static camera info, object owned by someone else, such as
222     // Camera2Device.
223     const CameraMetadata *info;
224 
225     // Fast-access static device information; this is a subset of the
226     // information available through the staticInfo() method, used for
227     // frequently-accessed values or values that have to be calculated from the
228     // static information.
229     struct DeviceInfo {
230         int32_t arrayWidth;
231         int32_t arrayHeight;
232         int32_t bestStillCaptureFpsRange[2];
233         uint8_t bestFaceDetectMode;
234         int32_t maxFaces;
235         struct OverrideModes {
236             flashMode_t flashMode;
237             uint8_t     wbMode;
238             focusMode_t focusMode;
OverrideModesParameters::DeviceInfo::OverrideModes239             OverrideModes():
240                     flashMode(FLASH_MODE_INVALID),
241                     wbMode(ANDROID_CONTROL_AWB_MODE_OFF),
242                     focusMode(FOCUS_MODE_INVALID) {
243             }
244         };
245         DefaultKeyedVector<uint8_t, OverrideModes> sceneModeOverrides;
246         bool isExternalCamera;
247         float defaultFocalLength;
248         bool useFlexibleYuv;
249         Size maxJpegSize;
250         Size maxZslSize;
251         bool supportsPreferredConfigs;
252     } fastInfo;
253 
254     // Quirks information; these are short-lived flags to enable workarounds for
255     // incomplete HAL implementations
256     struct Quirks {
257         bool triggerAfWithAuto;
258         bool useZslFormat;
259         bool meteringCropRegion;
260         bool partialResults;
261     } quirks;
262 
263     /**
264      * Parameter manipulation and setup methods
265      */
266 
267     Parameters(int cameraId, int cameraFacing);
268     ~Parameters();
269 
270     // Sets up default parameters
271     status_t initialize(CameraDeviceBase *device, int deviceVersion);
272 
273     // Build fast-access device static info from static info
274     status_t buildFastInfo(CameraDeviceBase *device);
275     // Query for quirks from static info
276     status_t buildQuirks();
277 
278     // Get entry from camera static characteristics information. min/maxCount
279     // are used for error checking the number of values in the entry. 0 for
280     // max/minCount means to do no bounds check in that direction. In case of
281     // error, the entry data pointer is null and the count is 0.
282     camera_metadata_ro_entry_t staticInfo(uint32_t tag,
283             size_t minCount=0, size_t maxCount=0, bool required=true) const;
284 
285     // Validate and update camera parameters based on new settings
286     status_t set(const String8 &paramString);
287 
288     // Retrieve the current settings
289     String8 get() const;
290 
291     // Update passed-in request for common parameters
292     status_t updateRequest(CameraMetadata *request) const;
293 
294     // Add/update JPEG entries in metadata
295     status_t updateRequestJpeg(CameraMetadata *request) const;
296 
297     /* Helper functions to override jpeg size for video snapshot */
298     // Override jpeg size by video size. Called during startRecording.
299     status_t overrideJpegSizeByVideoSize();
300     // Recover overridden jpeg size.  Called during stopRecording.
301     status_t recoverOverriddenJpegSize();
302     // if video snapshot size is currently overridden
303     bool isJpegSizeOverridden();
304     // whether zero shutter lag should be used for non-recording operation
305     bool useZeroShutterLag() const;
306 
307     // Get default focal length
308     status_t getDefaultFocalLength(CameraDeviceBase *camera);
309 
310     // Calculate the crop region rectangle, either tightly about the preview
311     // resolution, or a region just based on the active array; both take
312     // into account the current zoom level.
313     struct CropRegion {
314         float left;
315         float top;
316         float width;
317         float height;
318     };
319     CropRegion calculateCropRegion(bool previewOnly) const;
320 
321     // Calculate the field of view of the high-resolution JPEG capture
322     status_t calculatePictureFovs(float *horizFov, float *vertFov) const;
323 
324     // Static methods for debugging and converting between camera1 and camera2
325     // parameters
326 
327     static const char *getStateName(State state);
328 
329     static int formatStringToEnum(const char *format);
330     static const char *formatEnumToString(int format);
331 
332     static int wbModeStringToEnum(const char *wbMode);
333     static const char* wbModeEnumToString(uint8_t wbMode);
334     static int effectModeStringToEnum(const char *effectMode);
335     static int abModeStringToEnum(const char *abMode);
336     static int sceneModeStringToEnum(const char *sceneMode, uint8_t defaultScene);
337     static flashMode_t flashModeStringToEnum(const char *flashMode);
338     static const char* flashModeEnumToString(flashMode_t flashMode);
339     static focusMode_t focusModeStringToEnum(const char *focusMode);
340     static const char* focusModeEnumToString(focusMode_t focusMode);
341 
342     static status_t parseAreas(const char *areasCStr,
343             Vector<Area> *areas);
344 
345     enum AreaKind
346     {
347         AREA_KIND_FOCUS,
348         AREA_KIND_METERING
349     };
350     status_t validateAreas(const Vector<Area> &areas,
351                                   size_t maxRegions,
352                                   AreaKind areaKind) const;
353     static bool boolFromString(const char *boolStr);
354 
355     // Map from camera orientation + facing to gralloc transform enum
356     static int degToTransform(int degrees, bool mirror);
357 
358     // API specifies FPS ranges are done in fixed point integer, with LSB = 0.001.
359     // Note that this doesn't apply to the (deprecated) single FPS value.
360     static const int kFpsToApiScale = 1000;
361 
362     // Transform from (-1000,-1000)-(1000,1000) normalized coords from camera
363     // API to HAL3 (0,0)-(activePixelArray.width/height) coordinates
364     int normalizedXToArray(int x) const;
365     int normalizedYToArray(int y) const;
366 
367     // Transform from HAL3 (0,0)-(activePixelArray.width/height) coordinates to
368     // (-1000,-1000)-(1000,1000) normalized coordinates given a scaler crop
369     // region.
370     int arrayXToNormalizedWithCrop(int x, const CropRegion &scalerCrop) const;
371     int arrayYToNormalizedWithCrop(int y, const CropRegion &scalerCrop) const;
372 
373     struct Range {
374         int min;
375         int max;
376     };
377 
378     int32_t fpsFromRange(int32_t min, int32_t max) const;
379 
380 private:
381 
382     // Convert from viewfinder crop-region relative array coordinates
383     // to HAL3 sensor array coordinates
384     int cropXToArray(int x) const;
385     int cropYToArray(int y) const;
386 
387     // Convert from camera API (-1000,1000)-(1000,1000) normalized coords
388     // to viewfinder crop-region relative array coordinates
389     int normalizedXToCrop(int x) const;
390     int normalizedYToCrop(int y) const;
391 
392     // Given a scaler crop region, calculate preview crop region based on
393     // preview aspect ratio.
394     CropRegion calculatePreviewCrop(const CropRegion &scalerCrop) const;
395 
396     Vector<Size> availablePreviewSizes;
397     Vector<Size> availableVideoSizes;
398     // Get size list (that are no larger than limit) from static metadata.
399     // This method filtered size with minFrameDuration < MAX_PREVIEW_RECORD_DURATION_NS
400     status_t getFilteredSizes(Size limit, Vector<Size> *sizes);
401     // Get max size (from the size array) that matches the given aspect ratio.
402     Size getMaxSizeForRatio(float ratio, const int32_t* sizeArray, size_t count);
403 
404     // Helper function for overriding jpeg size for video snapshot
405     // Check if overridden jpeg size needs to be updated after Parameters::set.
406     // The behavior of this function is tailored to the implementation of Parameters::set.
407     // Do not use this function for other purpose.
408     status_t updateOverriddenJpegSize();
409 
410     struct StreamConfiguration {
411         int32_t format;
412         int32_t width;
413         int32_t height;
414         int32_t isInput;
415     };
416 
417     // Helper function extract available stream configuration
418     // Only valid since device HAL version 3.2
419     // returns an empty Vector if device HAL version does support it
420     Vector<StreamConfiguration> getStreamConfigurations();
421 
422     // Helper function to extract the suggested stream configurations
423     Vector<StreamConfiguration> getPreferredStreamConfigurations(int32_t usecaseId) const;
424 
425     // Helper function to get minimum frame duration for a jpeg size
426     // return -1 if input jpeg size cannot be found in supported size list
427     int64_t getJpegStreamMinFrameDurationNs(Parameters::Size size);
428 
429     // Helper function to get minimum frame duration for a size/format combination
430     // return -1 if input size/format combination cannot be found.
431     int64_t getMinFrameDurationNs(Parameters::Size size, int format);
432 
433     // Helper function to check if a given fps is supported by all the sizes with
434     // the same format.
435     // return true if the device doesn't support min frame duration metadata tag.
436     bool isFpsSupported(const Vector<Size> &size, int format, int32_t fps);
437 
438     // Helper function to get non-duplicated available output formats
439     SortedVector<int32_t> getAvailableOutputFormats();
440     // Helper function to get available output jpeg sizes
441     Vector<Size> getAvailableJpegSizes();
442     // Helper function to get maximum size in input Size vector.
443     // The maximum size is defined by comparing width first, when width ties comparing height.
444     Size getMaxSize(const Vector<Size>& sizes);
445 
446     // Helper function to filter and sort suggested sizes
447     Vector<Parameters::Size> getPreferredFilteredSizes(int32_t usecaseId, int32_t format) const;
448     // Helper function to get the suggested jpeg sizes
449     Vector<Size> getPreferredJpegSizes() const;
450     // Helper function to get the suggested preview sizes
451     Vector<Size> getPreferredPreviewSizes() const;
452     // Helper function to get the suggested video sizes
453     Vector<Size> getPreferredVideoSizes() const;
454 
455     int mDeviceVersion;
456     uint8_t mDefaultSceneMode;
457 };
458 
459 // This class encapsulates the Parameters class so that it can only be accessed
460 // by constructing a Lock object, which locks the SharedParameter's mutex.
461 class SharedParameters {
462   public:
SharedParameters(int cameraId,int cameraFacing)463     SharedParameters(int cameraId, int cameraFacing):
464             mParameters(cameraId, cameraFacing) {
465     }
466 
467     template<typename S, typename P>
468     class BaseLock {
469       public:
BaseLock(S & p)470         explicit BaseLock(S &p):
471                 mParameters(p.mParameters),
472                 mSharedParameters(p) {
473             mSharedParameters.mLock.lock();
474         }
475 
~BaseLock()476         ~BaseLock() {
477             mSharedParameters.mLock.unlock();
478         }
479         P &mParameters;
480       private:
481         // Disallow copying, default construction
482         BaseLock();
483         BaseLock(const BaseLock &);
484         BaseLock &operator=(const BaseLock &);
485         S &mSharedParameters;
486     };
487     typedef BaseLock<SharedParameters, Parameters> Lock;
488     typedef BaseLock<const SharedParameters, const Parameters> ReadLock;
489 
490     // Access static info, read-only and immutable, so no lock needed
491     camera_metadata_ro_entry_t staticInfo(uint32_t tag,
492             size_t minCount=0, size_t maxCount=0) const {
493         return mParameters.staticInfo(tag, minCount, maxCount);
494     }
495 
496     // Only use for dumping or other debugging
unsafeAccess()497     const Parameters &unsafeAccess() {
498         return mParameters;
499     }
500   private:
501     Parameters mParameters;
502     mutable Mutex mLock;
503 };
504 
505 
506 }; // namespace camera2
507 }; // namespace android
508 
509 #endif
510