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