1 /* 2 * Copyright (C) 2015 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 /** 18 * @addtogroup Camera 19 * @{ 20 */ 21 22 /** 23 * @file NdkCameraMetadata.h 24 */ 25 26 /* 27 * This file defines an NDK API. 28 * Do not remove methods. 29 * Do not change method signatures. 30 * Do not change the value of constants. 31 * Do not change the size of any of the classes defined in here. 32 * Do not reference types that are not part of the NDK. 33 * Do not #include files that aren't part of the NDK. 34 */ 35 36 #ifndef _NDK_CAMERA_METADATA_H 37 #define _NDK_CAMERA_METADATA_H 38 39 #include "NdkCameraError.h" 40 #include "NdkCameraMetadataTags.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * ACameraMetadata is opaque type that provides access to read-only camera metadata like camera 48 * characteristics (via {@link ACameraManager_getCameraCharacteristics}) or capture results (via 49 * {@link ACameraCaptureSession_captureCallback_result}). 50 */ 51 typedef struct ACameraMetadata ACameraMetadata; 52 53 /** 54 * Possible data types of a metadata entry. 55 * 56 * Keep in sync with system/media/include/system/camera_metadata.h 57 */ 58 enum { 59 /// Unsigned 8-bit integer (uint8_t) 60 ACAMERA_TYPE_BYTE = 0, 61 /// Signed 32-bit integer (int32_t) 62 ACAMERA_TYPE_INT32 = 1, 63 /// 32-bit float (float) 64 ACAMERA_TYPE_FLOAT = 2, 65 /// Signed 64-bit integer (int64_t) 66 ACAMERA_TYPE_INT64 = 3, 67 /// 64-bit float (double) 68 ACAMERA_TYPE_DOUBLE = 4, 69 /// A 64-bit fraction (ACameraMetadata_rational) 70 ACAMERA_TYPE_RATIONAL = 5, 71 /// Number of type fields 72 ACAMERA_NUM_TYPES 73 }; 74 75 /** 76 * Definition of rational data type in {@link ACameraMetadata}. 77 */ 78 typedef struct ACameraMetadata_rational { 79 int32_t numerator; 80 int32_t denominator; 81 } ACameraMetadata_rational; 82 83 /** 84 * A single camera metadata entry. 85 * 86 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the 87 * array.</p> 88 */ 89 typedef struct ACameraMetadata_entry { 90 /** 91 * The tag identifying the entry. 92 * 93 * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the 94 * entry should be interpreted and which parts of the API provide it. 95 * See {@link NdkCameraMetadataTags.h} for more details. </p> 96 */ 97 uint32_t tag; 98 99 /** 100 * The data type of this metadata entry. 101 * 102 * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the 103 * same type.</p> 104 */ 105 uint8_t type; 106 107 /** 108 * Count of elements (NOT count of bytes) in this metadata entry. 109 */ 110 uint32_t count; 111 112 /** 113 * Pointer to the data held in this metadata entry. 114 * 115 * <p>The type field above defines which union member pointer is valid. The count field above 116 * defines the length of the data in number of elements.</p> 117 */ 118 union { 119 uint8_t *u8; 120 int32_t *i32; 121 float *f; 122 int64_t *i64; 123 double *d; 124 ACameraMetadata_rational* r; 125 } data; 126 } ACameraMetadata_entry; 127 128 /** 129 * A single read-only camera metadata entry. 130 * 131 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the 132 * array.</p> 133 */ 134 typedef struct ACameraMetadata_const_entry { 135 /** 136 * The tag identifying the entry. 137 * 138 * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the 139 * entry should be interpreted and which parts of the API provide it. 140 * See {@link NdkCameraMetadataTags.h} for more details. </p> 141 */ 142 uint32_t tag; 143 144 /** 145 * The data type of this metadata entry. 146 * 147 * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the 148 * same type.</p> 149 */ 150 uint8_t type; 151 152 /** 153 * Count of elements (NOT count of bytes) in this metadata entry. 154 */ 155 uint32_t count; 156 157 /** 158 * Pointer to the data held in this metadata entry. 159 * 160 * <p>The type field above defines which union member pointer is valid. The count field above 161 * defines the length of the data in number of elements.</p> 162 */ 163 union { 164 const uint8_t *u8; 165 const int32_t *i32; 166 const float *f; 167 const int64_t *i64; 168 const double *d; 169 const ACameraMetadata_rational* r; 170 } data; 171 } ACameraMetadata_const_entry; 172 173 /** 174 * Get a metadata entry from an input {@link ACameraMetadata}. 175 * 176 * <p>The memory of the data field in the returned entry is managed by camera framework. Do not 177 * attempt to free it.</p> 178 * 179 * @param metadata the {@link ACameraMetadata} of interest. 180 * @param tag the tag value of the camera metadata entry to be get. 181 * @param entry the output {@link ACameraMetadata_const_entry} will be filled here if the method 182 * call succeeeds. 183 * 184 * @return <ul> 185 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 186 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata or entry is NULL.</li> 187 * <li>{@link ACAMERA_ERROR_METADATA_NOT_FOUND} if input metadata does not contain an entry 188 * of input tag value.</li></ul> 189 */ 190 camera_status_t ACameraMetadata_getConstEntry( 191 const ACameraMetadata* metadata, uint32_t tag, /*out*/ACameraMetadata_const_entry* entry); 192 193 /** 194 * List all the entry tags in input {@link ACameraMetadata}. 195 * 196 * @param metadata the {@link ACameraMetadata} of interest. 197 * @param numEntries number of metadata entries in input {@link ACameraMetadata} 198 * @param tags the tag values of the metadata entries. Length of tags is returned in numEntries 199 * argument. The memory is managed by ACameraMetadata itself and must NOT be free/delete 200 * by application. Do NOT access tags after calling ACameraMetadata_free. 201 * 202 * @return <ul> 203 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 204 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata, numEntries or tags is NULL.</li> 205 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 206 */ 207 camera_status_t ACameraMetadata_getAllTags( 208 const ACameraMetadata* metadata, /*out*/int32_t* numEntries, /*out*/const uint32_t** tags); 209 210 /** 211 * Create a copy of input {@link ACameraMetadata}. 212 * 213 * <p>The returned ACameraMetadata must be freed by the application by {@link ACameraMetadata_free} 214 * after application is done using it.</p> 215 * 216 * @param src the input {@link ACameraMetadata} to be copied. 217 * 218 * @return a valid ACameraMetadata pointer or NULL if the input metadata cannot be copied. 219 */ 220 ACameraMetadata* ACameraMetadata_copy(const ACameraMetadata* src); 221 222 /** 223 * Free a {@link ACameraMetadata} structure. 224 * 225 * @param metadata the {@link ACameraMetadata} to be freed. 226 */ 227 void ACameraMetadata_free(ACameraMetadata* metadata); 228 229 #ifdef __cplusplus 230 } // extern "C" 231 #endif 232 233 #endif //_NDK_CAMERA_METADATA_H 234 235 /** @} */ 236