Android Camera API2中采用CameraMetadata用于从APP到HAL的参数交互

前沿：

在全新的Camera API2架构下，常常会有人疑问再也看不到熟悉的SetParameter/Paramters等相关的身影，取而代之的是一种全新的CameraMetadata结构的出现，他不仅很早就出现在Camera API1/API2结构下的Camera2Device、Camera3Device中用于和HAL3的数据交互，而现在在API2的驱使下都取代了Parameter，实现了Java到native到hal3的参数传递。那么现在假如需要在APP中设置某一项控制参数，对于Camera API2而言，涉及到对Sensor相关参数的set/control时又需要做哪些工作呢？

1. camera_metadata类整体布局结构

主要涉及到的源文件包括camera_metadata_tags.h，camera_metadata_tag_info.c，CameraMetadata.cpp，camera_metadata.c。对于每个Metadata数据，其通过不同业务控制需求，将整个camera工作需要的参数划分成多个不同的Section，其中在camera_metadata_tag_info.c表定义了所有Camera需要使用到的Section段的Name：

[cpp] view plain copy

1. const char *camera_metadata_section_names[ANDROID_SECTION_COUNT] = {  
2.     [ANDROID_COLOR_CORRECTION]     = "android.colorCorrection",  
3.     [ANDROID_CONTROL]              = "android.control",  
4.     [ANDROID_DEMOSAIC]             = "android.demosaic",  
5.     [ANDROID_EDGE]                 = "android.edge",  
6.     [ANDROID_FLASH]                = "android.flash",  
7.     [ANDROID_FLASH_INFO]           = "android.flash.info",  
8.     [ANDROID_GEOMETRIC]            = "android.geometric",  
9.     [ANDROID_HOT_PIXEL]            = "android.hotPixel",  
10.     [ANDROID_HOT_PIXEL_INFO]       = "android.hotPixel.info",  
11.     [ANDROID_JPEG]                 = "android.jpeg",  
12.     [ANDROID_LENS]                 = "android.lens",  
13.     [ANDROID_LENS_INFO]            = "android.lens.info",  
14.     [ANDROID_NOISE_REDUCTION]      = "android.noiseReduction",  
15.     [ANDROID_QUIRKS]               = "android.quirks",  
16.     [ANDROID_REQUEST]              = "android.request",  
17.     [ANDROID_SCALER]               = "android.scaler",  
18.     [ANDROID_SENSOR]               = "android.sensor",  
19.     [ANDROID_SENSOR_INFO]          = "android.sensor.info",  
20.     [ANDROID_SHADING]              = "android.shading",  
21.     [ANDROID_STATISTICS]           = "android.statistics",  
22.     [ANDROID_STATISTICS_INFO]      = "android.statistics.info",  
23.     [ANDROID_TONEMAP]              = "android.tonemap",  
24.     [ANDROID_LED]                  = "android.led",  
25.     [ANDROID_INFO]                 = "android.info",  
26.     [ANDROID_BLACK_LEVEL]          = "android.blackLevel",  
27. };  

        对于每个Section端而言，其都占据一个索引区域section_bounds，比如ANDROID_CONTROL Section他所代表的control区域是从ANDROID_CONTROL_START到ANDROID_CONTROL_END之间，且每个Section所拥有的Index范围理论最大可到(1 << 16)大小，完全可以满足统一Section下不同的控制参数的维护。

以ANDROID_CONTROL为列，他的Section index = 1，即对应的section index区间可到（1<<16，2<<16)，但一般以实际section中维护的tag的数量来结束，即ANDROID_CONTROL_END决定最终的section index区间。对于每一个section，其下具备不同数量的tag，这个tag是一个指定section下的index值，通过该值来维护一个tag所在的数据区域，此外每个tag都有相应的string  name，在camera_metadata_tag_info.c通过struct tag_info_t来维护一个tag的相关属性：

[cpp] view plain copy

1. typedef struct tag_info {  
2.     const char *tag_name;  
3.     uint8_t     tag_type;  
4. } tag_info_t;  

其中tag_name为对应section下不同tag的name值 ，tag_type指定了这个tag所维护的数据类型，包括如下：

[cpp] view plain copy

1. enum {  
2.     // Unsigned 8-bit integer (uint8_t)  
3.     TYPE_BYTE = 0,  
4.     // Signed 32-bit integer (int32_t)  
5.     TYPE_INT32 = 1,  
6.     // 32-bit float (float)  
7.     TYPE_FLOAT = 2,  
8.     // Signed 64-bit integer (int64_t)  
9.     TYPE_INT64 = 3,  
10.     // 64-bit float (double)  
11.     TYPE_DOUBLE = 4,  
12.     // A 64-bit fraction (camera_metadata_rational_t)  
13.     TYPE_RATIONAL = 5,  
14.     // Number of type fields  
15.     NUM_TYPES  
16. };  

对每一个section所拥有的tag_info信息，通过全局结构体tag_info_t *tag_info[ANDROID_SECTION_COUNT] 来定义。

下图是对整个Camera Metadata对不同section以及相应section下不同tag的布局图，下图以最常见的Android.control Section为例进行了描述：

2. CameraMetadata通过camera_metadata来维护数据信息

      假设现在存在一个CameraMetadata对象，那么他是如何将一个tag标记的参数维护起来的呢？

[cpp] view plain copy

1. CameraMetadata::CameraMetadata(size_t entryCapacity, size_t dataCapacity) :  
2.         mLocked(false)  
3. {  
4.     mBuffer = allocate_camera_metadata(entryCapacity, dataCapacity);  
5. }  

[cpp] view plain copy

1. camera_metadata_t *allocate_camera_metadata(size_t entry_capacity,  
2.                                             size_t data_capacity) {  
3.     if (entry_capacity == 0) return NULL;  
4.   
5.     size_t memory_needed = calculate_camera_metadata_size(entry_capacity,  
6.                                                           data_capacity);  
7.     void *buffer = malloc(memory_needed);  
8.     return place_camera_metadata(buffer, memory_needed,  
9.                                  entry_capacity,  
10.                                  data_capacity);  
11. }  

一个CameraMetadata数据内存块中组成的最小基本单元是struct camera_metadata_buffer_entry，总的entry数目等信息需要 struct  camera_metadata_t来维护：

[cpp] view plain copy

1. struct camera_metadata {  
2.     size_t                   size;  
3.     uint32_t                 version;  
4.     uint32_t                 flags;  
5.     size_t                   entry_count;//当前实际的entry数目  
6.     size_t                   entry_capacity;//entry最大可以存储的数目  
7.     uptrdiff_t               entries_start; // Offset from camera_metadata  
8.     size_t                   data_count;//当前占据的数据空间  
9.     size_t                   data_capacity;//最大可操作的数据容量  
10.     uptrdiff_t               data_start; // Offset from camera_metadata，大容量数据存储的起始地址  
11.     void                    *user; // User set pointer, not copied with buffer  
12.     uint8_t                  reserved[0];  
13. };  

对于每一个entry主要记录他的所代表的TAG，以及这个TAG的需要存储的数据类型，此外还需要记录这个entry是否是需要一个union offset来表示他当前数据量过大时的数据存储位置，

[cpp] view plain copy

1. typedef struct camera_metadata_buffer_entry {  
2.     uint32_t tag;//表示当时这个entry代表的tag值，即上文提到的section中不同的tag index值  
3.     size_t   count;  
4.     union {  
5.         size_t  offset;  
6.         uint8_t value[4];  
7.     } data;//如果存储的数据量不大于4则直接存储。否则需要指点一个offset来表示便宜  
8.     uint8_t  type;//维护的数据类型  
9.     uint8_t  reserved[3];  
10. } camera_metadata_buffer_entry_t;  

3. update更新并建立参数

CameraMetadata支持不同类型的数据更新或者保存到camera_metadata_t中tag所在的entry当中去，以一个更新单字节的数据为例，data_count指定了数据的个数，而tag指定了要更新的entry。

[cpp] view plain copy

1. status_t CameraMetadata::update(uint32_t tag,  
2.         const uint8_t *data, size_t data_count) {  
3.     status_t res;  
4.     if (mLocked) {  
5.         ALOGE("%s: CameraMetadata is locked", __FUNCTION__);  
6.         return INVALID_OPERATION;  
7.     }  
8.     if ( (res = checkType(tag, TYPE_BYTE)) != OK) {  
9.         return res;  
10.     }  
11.     return updateImpl(tag, (const void*)data, data_count);  
12. }  

首先是通过checkType，主要是通过tag找到get_camera_metadata_tag_type其所应当支持的tag_type( 因为具体的TAG是已经通过camera_metadata_tag_info.c源文件中的tag_info这个表指定了其应该具备的tag_type)，比较两者是否一致，一致后才允许后续的操作，如这里需要TYPE_BYTE一致。

[cpp] view plain copy

1. const char *get_camera_metadata_tag_name(uint32_t tag) {  
2.     uint32_t tag_section = tag >> 16;  
3.     if (tag_section >= VENDOR_SECTION && vendor_tag_ops != NULL) {  
4.         return vendor_tag_ops->get_tag_name(  
5.             vendor_tag_ops,  
6.             tag);  
7.     }  
8.     if (tag_section >= ANDROID_SECTION_COUNT ||  
9.         tag >= camera_metadata_section_bounds[tag_section][1] ) {  
10.         return NULL;  
11.     }  
12.     uint32_t tag_index = tag & 0xFFFF;//取tag在section中的index，低16位  
13.     return tag_info[tag_section][tag_index].tag_name;//定位section然后再说tag  
14. }  
15.   
16. int get_camera_metadata_tag_type(uint32_t tag) {  
17.     uint32_t tag_section = tag >> 16;  
18.     if (tag_section >= VENDOR_SECTION && vendor_tag_ops != NULL) {  
19.         return vendor_tag_ops->get_tag_type(  
20.             vendor_tag_ops,  
21.             tag);  
22.     }  
23.     if (tag_section >= ANDROID_SECTION_COUNT ||  
24.             tag >= camera_metadata_section_bounds[tag_section][1] ) {  
25.         return -1;  
26.     }  
27.     uint32_t tag_index = tag & 0xFFFF;  
28.     return tag_info[tag_section][tag_index].tag_type;  
29. }  

分别是通过tag取货section id即tag>>16，就定位到所属的section tag_info_t[]，再通过在在该section中定位tag index一般是tag&0xFFFF的低16位为在该tag在section中的偏移值，进而找到tag自身的struct tag_info_t.

updataImpl函数主要是讲所有要写入的数据进行update操作。

[cpp] view plain copy

1. status_t CameraMetadata::updateImpl(uint32_t tag, const void *data,  
2.         size_t data_count) {  
3.     status_t res;  
4.     if (mLocked) {  
5.         ALOGE("%s: CameraMetadata is locked", __FUNCTION__);  
6.         return INVALID_OPERATION;  
7.     }  
8.     int type = get_camera_metadata_tag_type(tag);  
9.     if (type == -1) {  
10.         ALOGE("%s: Tag %d not found", __FUNCTION__, tag);  
11.         return BAD_VALUE;  
12.     }  
13.     size_t data_size = calculate_camera_metadata_entry_data_size(type,  
14.             data_count);  
15.   
16.     res = resizeIfNeeded(1, data_size);//新建camera_metadata_t  
17.   
18.     if (res == OK) {  
19.         camera_metadata_entry_t entry;  
20.         res = find_camera_metadata_entry(mBuffer, tag, &entry);  
21.         if (res == NAME_NOT_FOUND) {  
22.             res = add_camera_metadata_entry(mBuffer,  
23.                     tag, data, data_count);//将当前新的tag以及数据加入到camera_metadata_t  
24.         } else if (res == OK) {  
25.             res = update_camera_metadata_entry(mBuffer,  
26.                     entry.index, data, data_count, NULL);  
27.         }  
28.     }  
29.   
30.     if (res != OK) {  
31.         ALOGE("%s: Unable to update metadata entry %s.%s (%x): %s (%d)",  
32.                 __FUNCTION__, get_camera_metadata_section_name(tag),  
33.                 get_camera_metadata_tag_name(tag), tag, strerror(-res), res);  
34.     }  
35.   
36.     IF_ALOGV() {  
37.         ALOGE_IF(validate_camera_metadata_structure(mBuffer, /*size*/NULL) !=  
38.                  OK,  
39.   
40.                  "%s: Failed to validate metadata structure after update %p",  
41.                  __FUNCTION__, mBuffer);  
42.     }  
43.   
44.     return res;  
45. }  

主要分为以下几个过程：

a.通过tag_type存储的数据类型，由calculate_camera_metadata_entry_data_size计算要写入的entry中的数据量。

b. resizeIfNeeded通过已有entry的数量等，增加entry_capacity，或者重建整个camera_metadata_t，为后续增加数据创建内存空间基础。

c. 通过find_camera_metadata_entry获取一个entry的入口camera_metadata_entry_t，如果存在这个tag对应的entry，则将camera_metadata_buffer_entry_t的属性信息转为camera_metadata_entry_t。

[cpp] view plain copy

1. typedef struct camera_metadata_entry {  
2.     size_t   index;//在当前的entry排序中，其所在的index值  
3.     uint32_t tag;  
4.     uint8_t  type;  
5.     size_t   count;  
6.     union {  
7.         uint8_t *u8;  
8.         int32_t *i32;  
9.         float   *f;  
10.         int64_t *i64;  
11.         double  *d;  
12.         camera_metadata_rational_t *r;  
13.     } data;//针对不同数据类型，u8表示数据存储的入口地址，不大于4字节即为value[4].  
14. } camera_metadata_entry_t;  

d .add_camera_metadata_entry完成全新的entry更新与写入，即这个TAG目前不存在于这个camera_metadata_t中；update_camera_metadata_entry则是直接完成数据的更新。

[cpp] view plain copy

1. mPreviewBuilder.set(CaptureRequest.CONTROL_AF_MODE,  
2.                         CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);  
3.                 mPreviewBuilder.set(CaptureRequest.CONTROL_AE_MODE,  
4.                         CaptureRequest.CONTROL_AE_MODE_ON_AUTO_FLASH);  
5.                 session.setRepeatingRequest(mPreviewBuilder.build(), mSessionCaptureCallback, mHandler);  

4. Java层中CameraMetadata.java和CameraMetadataNative.java

下面以API2中java层中设置AF的工作模式为例，来说明这个参数设置的过程：

[java] view plain copy

1. mPreviewBuilder.set(CaptureRequest.CONTROL_AF_MODE,  
2.                         CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);  
3.                 mPreviewBuilder.set(CaptureRequest.CONTROL_AE_MODE,  
4.                         CaptureRequest.CONTROL_AE_MODE_ON_AUTO_FLASH);  
5.                 session.setRepeatingRequest(mPreviewBuilder.build(), mSessionCaptureCallback, mHandler);  

其中CONTROL_AF_MODE定义在CaptureRequest,java中如下以一个Key的形式存在：

[cpp] view plain copy

1. public static final Key<Integer> CONTROL_AF_MODE =  
2.         new Key<Integer>("android.control.afMode", int.class);  

[java] view plain copy

1. public Key(String name, Class<T> type) {  
2.     mKey = new CameraMetadataNative.Key<T>(name, type);  
3. }  

在CameraMetadataNative.java中Key的构造

[java] view plain copy

1. public Key(String name, Class<T> type) {  
2.            if (name == null) {  
3.                throw new NullPointerException("Key needs a valid name");  
4.            } else if (type == null) {  
5.                throw new NullPointerException("Type needs to be non-null");  
6.            }  
7.            mName = name;  
8.            mType = type;  
9.            mTypeReference = TypeReference.createSpecializedTypeReference(type);  
10.            mHash = mName.hashCode() ^ mTypeReference.hashCode();  
11.        }  

其中CONTROL_AF_MODE_CONTINUOUS_PICTURE定义在 CameraMetadata. java中

[cpp] view plain copy

1. public static final int CONTROL_AF_MODE_CONTINUOUS_PICTURE = 4;  

逐一定位set的入口：

a. mPreviewBuilder是CaptureRequest.java的build类，其会构建一个CaptureRequest

[cpp] view plain copy

1. public Builder(CameraMetadataNative template) {  
2.     mRequest = new CaptureRequest(template);  
3. }  

[java] view plain copy

1. private CaptureRequest() {  
2.     mSettings = new CameraMetadataNative();  
3.     mSurfaceSet = new HashSet<Surface>();  
4. }  

mSetting建立的是一个CameraMetadataNative对象，主要用于和Native层进行接口交互，构造如下

[java] view plain copy

1. public CameraMetadataNative() {  
2.     super();  
3.     mMetadataPtr = nativeAllocate();  
4.     if (mMetadataPtr == 0) {  
5.         throw new OutOfMemoryError("Failed to allocate native CameraMetadata");  
6.     }  
7. }  

b. CaptureRequest.Build.set()

[cpp] view plain copy

1. public <T> void set(Key<T> key, T value) {  
2.     mRequest.mSettings.set(key, value);  
3. }  

[java] view plain copy

1. public <T> void set(CaptureRequest.Key<T> key, T value) {  
2.     set(key.getNativeKey(), value);  
3. }  

考虑到CaptureRequest extend CameraMetadata，则 CaptureRequest.java中getNativeKey

[java] view plain copy

1. public CameraMetadataNative.Key<T> getNativeKey() {  
2.     return mKey;  
3. }  

mKey即为之前构造的CameraMetadataNative.Key.

[java] view plain copy

1. public <T> void set(Key<T> key, T value) {  
2.     SetCommand s = sSetCommandMap.get(key);  
3.     if (s != null) {  
4.         s.setValue(this, value);  
5.         return;  
6.     }  
7.     setBase(key, value);  
8. }  

[java] view plain copy

1. private <T> void setBase(Key<T> key, T value) {  
2.     int tag = key.getTag();  
3.   
4.     if (value == null) {  
5.         // Erase the entry  
6.         writeValues(tag, /*src*/null);  
7.         return;  
8.     } // else update the entry to a new value  
9.   
10.     Marshaler<T> marshaler = getMarshalerForKey(key);  
11.     int size = marshaler.calculateMarshalSize(value);  
12.   
13.     // TODO: Optimization. Cache the byte[] and reuse if the size is big enough.  
14.     byte[] values = new byte[size];  
15.   
16.     ByteBuffer buffer = ByteBuffer.wrap(values).order(ByteOrder.nativeOrder());  
17.     marshaler.marshal(value, buffer);  
18.   
19.     writeValues(tag, values);  
20. }  

首先来看key.getTag()函数的实现，他是将这个key交由Native层后转为一个真正的在Java层中的tag值：

[java] view plain copy

1. public final int getTag() {  
2.     if (!mHasTag) {  
3.         mTag = CameraMetadataNative.getTag(mName);  
4.         mHasTag = true;  
5.     }  
6.     return mTag;  
7. }  

[java] view plain copy

1. public static int getTag(String key) {  
2.     return nativeGetTagFromKey(key);  
3. }  

是将Java层的String交由Native来转为一个Java层的tag值。再来看writeValues的实现，同样调用的是一个native接口，很好的阐明了CameraMetadataNative的意思：

[java] view plain copy

1. public void writeValues(int tag, byte[] src) {  
2.     nativeWriteValues(tag, src);  
3. }  

相关native层的实现在下一小节说明。

5. Native层的CameraMetadata结构完成camera参数的传递

    在描述万了CameraMetadata数据的相关操作之后，可明确的一点是SECTION下的TAG是操作他的核心所在。

这里先说明一个在API1 Camera2Client 参数传递的过程，他采用的逻辑是还是在Java层预留了setParameters接口，只是当Parameter在设置时比起CameraClient而言，他是将这个Parameter根据不同的TAG形式直接绑定到CameraMetadata mPreviewRequest/mRecordRequest/mCaptureRequest中，这些数据会由Capture_Request转为camera3_capture_request中的camera_metadata_t settings完成参数从Java到native到HAL3的传递。

但是在Camera API2下，不再需要那么复杂的转换过程，在Java层中直接对参数进行设置并将其封装到Capture_Request即可，即参数控制由Java层来完成。这也体现了API2中Request和Result在APP中就大量存在的原因。对此为了和Framework Native层相关TAG数据的统一，在Java层中大量出现的参数设置是通过Section Tag的name来交由Native完成转换生成在Java层的TAG。

对于第三小节中提到的native层的实现，其对应的实现函数位于android_hardware_camera2_CameraMetadata.c中，如CameraMetadata_getTagFromKey是实现将一个Java层的string转为一个tag的值，他的主要原理如下：根据传入的key string值本质是由一个字符串组成的如上文中提到的android.control.mode。对比最初不同的Section name就可以发现前面两个x.y的字符串就是代表是Section name.而后面mode即是在该section下的tag数值，所以通过对这个string的分析可知，就可以定位他的section以及tag值。这样返回到Java层的就是key相应的tag值了。

如果要写数据，那么在native同样需要一个CameraMetadata对象，这里是在Java构造CameraMetadataNative时实现的，调用的native接口是nativeAllocate()：

[cpp] view plain copy

1. static jlong CameraMetadata_allocate(JNIEnv *env, jobject thiz) {  
2.     ALOGV("%s", __FUNCTION__);  
3.   
4.     return reinterpret_cast<jlong>(new CameraMetadata());  
5. }  

最终可以明确的是CameraMetadata相关的参数是被Java层来set/get，但本质是在native层进行了实现，后续如果相关控制参数是被打包到CaptureRequest中时传入到native时即操作的还是native中的 CameraMetadata。