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 <stdint.h> 40 #include <sys/cdefs.h> 41 42 #ifndef __ANDROID_VNDK__ 43 #if __ANDROID_API__ >= 30 44 #include "jni.h" 45 #endif /* __ANDROID_API__ >= 30 */ 46 #endif /* __ANDROID_VNDK__ */ 47 48 #include "NdkCameraError.h" 49 #include "NdkCameraMetadataTags.h" 50 51 __BEGIN_DECLS 52 53 #if __ANDROID_API__ >= 24 54 55 /** 56 * ACameraMetadata is opaque type that provides access to read-only camera metadata like camera 57 * characteristics (via {@link ACameraManager_getCameraCharacteristics}) or capture results (via 58 * {@link ACameraCaptureSession_captureCallback_result}). 59 */ 60 typedef struct ACameraMetadata ACameraMetadata; 61 62 /** 63 * Possible data types of a metadata entry. 64 * 65 * Keep in sync with system/media/include/system/camera_metadata.h 66 */ 67 enum { 68 /// Unsigned 8-bit integer (uint8_t) 69 ACAMERA_TYPE_BYTE = 0, 70 /// Signed 32-bit integer (int32_t) 71 ACAMERA_TYPE_INT32 = 1, 72 /// 32-bit float (float) 73 ACAMERA_TYPE_FLOAT = 2, 74 /// Signed 64-bit integer (int64_t) 75 ACAMERA_TYPE_INT64 = 3, 76 /// 64-bit float (double) 77 ACAMERA_TYPE_DOUBLE = 4, 78 /// A 64-bit fraction (ACameraMetadata_rational) 79 ACAMERA_TYPE_RATIONAL = 5, 80 /// Number of type fields 81 ACAMERA_NUM_TYPES 82 }; 83 84 /** 85 * Definition of rational data type in {@link ACameraMetadata}. 86 */ 87 typedef struct ACameraMetadata_rational { 88 int32_t numerator; 89 int32_t denominator; 90 } ACameraMetadata_rational; 91 92 /** 93 * A single camera metadata entry. 94 * 95 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the 96 * array.</p> 97 */ 98 typedef struct ACameraMetadata_entry { 99 /** 100 * The tag identifying the entry. 101 * 102 * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the 103 * entry should be interpreted and which parts of the API provide it. 104 * See {@link NdkCameraMetadataTags.h} for more details. </p> 105 */ 106 uint32_t tag; 107 108 /** 109 * The data type of this metadata entry. 110 * 111 * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the 112 * same type.</p> 113 */ 114 uint8_t type; 115 116 /** 117 * Count of elements (NOT count of bytes) in this metadata entry. 118 */ 119 uint32_t count; 120 121 /** 122 * Pointer to the data held in this metadata entry. 123 * 124 * <p>The type field above defines which union member pointer is valid. The count field above 125 * defines the length of the data in number of elements.</p> 126 */ 127 union { 128 uint8_t *u8; 129 int32_t *i32; 130 float *f; 131 int64_t *i64; 132 double *d; 133 ACameraMetadata_rational* r; 134 } data; 135 } ACameraMetadata_entry; 136 137 /** 138 * A single read-only camera metadata entry. 139 * 140 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the 141 * array.</p> 142 */ 143 typedef struct ACameraMetadata_const_entry { 144 /** 145 * The tag identifying the entry. 146 * 147 * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the 148 * entry should be interpreted and which parts of the API provide it. 149 * See {@link NdkCameraMetadataTags.h} for more details. </p> 150 */ 151 uint32_t tag; 152 153 /** 154 * The data type of this metadata entry. 155 * 156 * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the 157 * same type.</p> 158 */ 159 uint8_t type; 160 161 /** 162 * Count of elements (NOT count of bytes) in this metadata entry. 163 */ 164 uint32_t count; 165 166 /** 167 * Pointer to the data held in this metadata entry. 168 * 169 * <p>The type field above defines which union member pointer is valid. The count field above 170 * defines the length of the data in number of elements.</p> 171 */ 172 union { 173 const uint8_t *u8; 174 const int32_t *i32; 175 const float *f; 176 const int64_t *i64; 177 const double *d; 178 const ACameraMetadata_rational* r; 179 } data; 180 } ACameraMetadata_const_entry; 181 182 /** 183 * Get a metadata entry from an input {@link ACameraMetadata}. 184 * 185 * <p>The memory of the data field in the returned entry is managed by camera framework. Do not 186 * attempt to free it.</p> 187 * 188 * @param metadata the {@link ACameraMetadata} of interest. 189 * @param tag the tag value of the camera metadata entry to be get. 190 * @param entry the output {@link ACameraMetadata_const_entry} will be filled here if the method 191 * call succeeeds. 192 * 193 * @return <ul> 194 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 195 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata or entry is NULL.</li> 196 * <li>{@link ACAMERA_ERROR_METADATA_NOT_FOUND} if input metadata does not contain an entry 197 * of input tag value.</li></ul> 198 */ 199 camera_status_t ACameraMetadata_getConstEntry( 200 const ACameraMetadata* metadata, 201 uint32_t tag, /*out*/ACameraMetadata_const_entry* entry) __INTRODUCED_IN(24); 202 203 /** 204 * List all the entry tags in input {@link ACameraMetadata}. 205 * 206 * @param metadata the {@link ACameraMetadata} of interest. 207 * @param numEntries number of metadata entries in input {@link ACameraMetadata} 208 * @param tags the tag values of the metadata entries. Length of tags is returned in numEntries 209 * argument. The memory is managed by ACameraMetadata itself and must NOT be free/delete 210 * by application. Do NOT access tags after calling ACameraMetadata_free. 211 * 212 * @return <ul> 213 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 214 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata, numEntries or tags is NULL.</li> 215 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 216 */ 217 camera_status_t ACameraMetadata_getAllTags( 218 const ACameraMetadata* metadata, 219 /*out*/int32_t* numEntries, /*out*/const uint32_t** tags) __INTRODUCED_IN(24); 220 221 /** 222 * Create a copy of input {@link ACameraMetadata}. 223 * 224 * <p>The returned ACameraMetadata must be freed by the application by {@link ACameraMetadata_free} 225 * after application is done using it.</p> 226 * 227 * @param src the input {@link ACameraMetadata} to be copied. 228 * 229 * @return a valid ACameraMetadata pointer or NULL if the input metadata cannot be copied. 230 */ 231 ACameraMetadata* ACameraMetadata_copy(const ACameraMetadata* src) __INTRODUCED_IN(24); 232 233 /** 234 * Free a {@link ACameraMetadata} structure. 235 * 236 * @param metadata the {@link ACameraMetadata} to be freed. 237 */ 238 void ACameraMetadata_free(ACameraMetadata* metadata) __INTRODUCED_IN(24); 239 240 #endif /* __ANDROID_API__ >= 24 */ 241 242 #if __ANDROID_API__ >= 29 243 244 /** 245 * Helper function to check if a camera is logical multi-camera. 246 * 247 * <p> Check whether a camera device is a logical multi-camera based on its 248 * static metadata. If it is, also returns its physical sub camera Ids.</p> 249 * 250 * @param staticMetadata the static metadata of the camera being checked. 251 * @param numPhysicalCameras returns the number of physical cameras. 252 * @param physicalCameraIds returns the array of physical camera Ids backing this logical 253 * camera device. Note that this pointer is only valid 254 * during the lifetime of the staticMetadata object. 255 * 256 * @return true if this is a logical multi-camera, false otherwise. 257 */ 258 bool ACameraMetadata_isLogicalMultiCamera(const ACameraMetadata* staticMetadata, 259 /*out*/size_t* numPhysicalCameras, /*out*/const char* const** physicalCameraIds) 260 __INTRODUCED_IN(29); 261 262 #endif /* __ANDROID_API__ >= 29 */ 263 264 #ifndef __ANDROID_VNDK__ 265 #if __ANDROID_API__ >= 30 266 267 /** 268 * Return a {@link ACameraMetadata} that references the same data as 269 * {@link cameraMetadata}, which is an instance of 270 * {@link android.hardware.camera2.CameraMetadata} (e.g., a 271 * {@link android.hardware.camera2.CameraCharacteristics} or 272 * {@link android.hardware.camera2.CaptureResult}). 273 * 274 * <p>The returned ACameraMetadata must be freed by the application by {@link ACameraMetadata_free} 275 * after application is done using it.</p> 276 * 277 * <p>The ACameraMetadata maintains a reference count to the underlying data, so 278 * it can be used independently of the Java object, and it remains valid even if 279 * the Java metadata is garbage collected. 280 * 281 * @param env the JNI environment. 282 * @param cameraMetadata the source {@link android.hardware.camera2.CameraMetadata} from which the 283 * returned {@link ACameraMetadata} is a view. 284 * 285 * @return a valid ACameraMetadata pointer or NULL if {@link cameraMetadata} is null or not a valid 286 * instance of {@link android.hardware.camera2.CameraMetadata}. 287 * 288 */ 289 ACameraMetadata* ACameraMetadata_fromCameraMetadata(JNIEnv* env, jobject cameraMetadata) 290 __INTRODUCED_IN(30); 291 292 #endif /* __ANDROID_API__ >= 30 */ 293 #endif /* __ANDROID_VNDK__ */ 294 295 __END_DECLS 296 297 #endif /* _NDK_CAMERA_METADATA_H */ 298 299 /** @} */ 300