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