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