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