camera_metadata.h revision 2cae02cd02ea0b5d04268621616d386c9d5261c6
1/* 2 * Copyright (C) 2012 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#ifndef SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_METADATA_H 18#define SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_METADATA_H 19 20#include <string.h> 21#include <stdint.h> 22#include <cutils/compiler.h> 23 24#ifdef __cplusplus 25extern "C" { 26#endif 27 28/** 29 * Tag hierarchy and enum definitions for camera_metadata_entry 30 * ============================================================================= 31 */ 32 33/** 34 * Main enum definitions are in a separate file to make it easy to 35 * maintain 36 */ 37#include "camera_metadata_tags.h" 38 39/** 40 * Enum range for each top-level category 41 */ 42ANDROID_API 43extern unsigned int camera_metadata_section_bounds[ANDROID_SECTION_COUNT][2]; 44ANDROID_API 45extern const char *camera_metadata_section_names[ANDROID_SECTION_COUNT]; 46 47/** 48 * Type definitions for camera_metadata_entry 49 * ============================================================================= 50 */ 51enum { 52 // Unsigned 8-bit integer (uint8_t) 53 TYPE_BYTE = 0, 54 // Signed 32-bit integer (int32_t) 55 TYPE_INT32 = 1, 56 // 32-bit float (float) 57 TYPE_FLOAT = 2, 58 // Signed 64-bit integer (int64_t) 59 TYPE_INT64 = 3, 60 // 64-bit float (double) 61 TYPE_DOUBLE = 4, 62 // A 64-bit fraction (camera_metadata_rational_t) 63 TYPE_RATIONAL = 5, 64 // Number of type fields 65 NUM_TYPES 66}; 67 68typedef struct camera_metadata_rational { 69 int32_t numerator; 70 int32_t denominator; 71} camera_metadata_rational_t; 72 73/** 74 * A reference to a metadata entry in a buffer. 75 * 76 * The data union pointers point to the real data in the buffer, and can be 77 * modified in-place if the count does not need to change. The count is the 78 * number of entries in data of the entry's type, not a count of bytes. 79 */ 80typedef struct camera_metadata_entry { 81 size_t index; 82 uint32_t tag; 83 uint8_t type; 84 size_t count; 85 union { 86 uint8_t *u8; 87 int32_t *i32; 88 float *f; 89 int64_t *i64; 90 double *d; 91 camera_metadata_rational_t *r; 92 } data; 93} camera_metadata_entry_t; 94 95/** 96 * Size in bytes of each entry type 97 */ 98ANDROID_API 99extern const size_t camera_metadata_type_size[NUM_TYPES]; 100 101/** 102 * Human-readable name of each entry type 103 */ 104ANDROID_API 105extern const char* camera_metadata_type_names[NUM_TYPES]; 106 107/** 108 * Main definitions for the metadata entry and array structures 109 * ============================================================================= 110 */ 111 112/** 113 * A packet of metadata. This is a list of metadata entries, each of which has 114 * an integer tag to identify its meaning, 'type' and 'count' field, and the 115 * data, which contains a 'count' number of entries of type 'type'. The packet 116 * has a fixed capacity for entries and for extra data. A new entry uses up one 117 * entry slot, and possibly some amount of data capacity; the function 118 * calculate_camera_metadata_entry_data_size() provides the amount of data 119 * capacity that would be used up by an entry. 120 * 121 * Entries are not sorted by default, and are not forced to be unique - multiple 122 * entries with the same tag are allowed. The packet will not dynamically resize 123 * when full. 124 * 125 * The packet is contiguous in memory, with size in bytes given by 126 * get_camera_metadata_size(). Therefore, it can be copied safely with memcpy() 127 * to a buffer of sufficient size. The copy_camera_metadata() function is 128 * intended for eliminating unused capacity in the destination packet. 129 */ 130struct camera_metadata; 131typedef struct camera_metadata camera_metadata_t; 132 133/** 134 * Functions for manipulating camera metadata 135 * ============================================================================= 136 */ 137 138/** 139 * Allocate a new camera_metadata structure, with some initial space for entries 140 * and extra data. The entry_capacity is measured in entry counts, and 141 * data_capacity in bytes. The resulting structure is all contiguous in memory, 142 * and can be freed with free_camera_metadata(). 143 */ 144ANDROID_API 145camera_metadata_t *allocate_camera_metadata(size_t entry_capacity, 146 size_t data_capacity); 147 148/** 149 * Place a camera metadata structure into an existing buffer. Returns NULL if 150 * the buffer is too small for the requested number of reserved entries and 151 * bytes of data. The entry_capacity is measured in entry counts, and 152 * data_capacity in bytes. If the buffer is larger than the required space, 153 * unused space will be left at the end. If successful, returns a pointer to the 154 * metadata header placed at the start of the buffer. It is the caller's 155 * responsibility to free the original buffer; do not call 156 * free_camera_metadata() with the returned pointer. 157 */ 158ANDROID_API 159camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size, 160 size_t entry_capacity, 161 size_t data_capacity); 162 163/** 164 * Free a camera_metadata structure. Should only be used with structures 165 * allocated with allocate_camera_metadata(). 166 */ 167ANDROID_API 168void free_camera_metadata(camera_metadata_t *metadata); 169 170/** 171 * Calculate the buffer size needed for a metadata structure of entry_count 172 * metadata entries, needing a total of data_count bytes of extra data storage. 173 */ 174ANDROID_API 175size_t calculate_camera_metadata_size(size_t entry_count, 176 size_t data_count); 177 178/** 179 * Get current size of entire metadata structure in bytes, including reserved 180 * but unused space. 181 */ 182ANDROID_API 183size_t get_camera_metadata_size(const camera_metadata_t *metadata); 184 185/** 186 * Get size of entire metadata buffer in bytes, not including reserved but 187 * unused space. This is the amount of space needed by copy_camera_metadata for 188 * its dst buffer. 189 */ 190ANDROID_API 191size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata); 192 193/** 194 * Get the current number of entries in the metadata packet. 195 */ 196ANDROID_API 197size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata); 198 199/** 200 * Get the maximum number of entries that could fit in the metadata packet. 201 */ 202ANDROID_API 203size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata); 204 205/** 206 * Get the current count of bytes used for value storage in the metadata packet. 207 */ 208ANDROID_API 209size_t get_camera_metadata_data_count(const camera_metadata_t *metadata); 210 211/** 212 * Get the maximum count of bytes that could be used for value storage in the 213 * metadata packet. 214 */ 215ANDROID_API 216size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata); 217 218/** 219 * Copy a metadata structure to a memory buffer, compacting it along the 220 * way. That is, in the copied structure, entry_count == entry_capacity, and 221 * data_count == data_capacity. 222 * 223 * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the 224 * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns 225 * NULL. Otherwise returns a pointer to the metadata structure header placed at 226 * the start of dst. 227 * 228 * Since the buffer was not allocated by allocate_camera_metadata, the caller is 229 * responsible for freeing the underlying buffer when needed; do not call 230 * free_camera_metadata. 231 */ 232ANDROID_API 233camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size, 234 const camera_metadata_t *src); 235 236/** 237 * Append camera metadata in src to an existing metadata structure in dst. This 238 * does not resize the destination structure, so if it is too small, a non-zero 239 * value is returned. On success, 0 is returned. Appending onto a sorted 240 * structure results in a non-sorted combined structure. 241 */ 242ANDROID_API 243int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src); 244 245/** 246 * Clone an existing metadata buffer, compacting along the way. This is 247 * equivalent to allocating a new buffer of the minimum needed size, then 248 * appending the buffer to be cloned into the new buffer. The resulting buffer 249 * can be freed with free_camera_metadata(). Returns NULL if cloning failed. 250 */ 251ANDROID_API 252camera_metadata_t *clone_camera_metadata(camera_metadata_t *src); 253 254/** 255 * Calculate the number of bytes of extra data a given metadata entry will take 256 * up. That is, if entry of 'type' with a payload of 'data_count' values is 257 * added, how much will the value returned by get_camera_metadata_data_count() 258 * be increased? This value may be zero, if no extra data storage is needed. 259 */ 260ANDROID_API 261size_t calculate_camera_metadata_entry_data_size(uint8_t type, 262 size_t data_count); 263 264/** 265 * Add a metadata entry to a metadata structure. Returns 0 if the addition 266 * succeeded. Returns a non-zero value if there is insufficient reserved space 267 * left to add the entry, or if the tag is unknown. data_count is the number of 268 * entries in the data array of the tag's type, not a count of 269 * bytes. Vendor-defined tags can not be added using this method, unless 270 * set_vendor_tag_query_ops() has been called first. Entries are always added to 271 * the end of the structure (highest index), so after addition, a 272 * previously-sorted array will be marked as unsorted. 273 */ 274ANDROID_API 275int add_camera_metadata_entry(camera_metadata_t *dst, 276 uint32_t tag, 277 const void *data, 278 size_t data_count); 279 280/** 281 * Sort the metadata buffer for fast searching. If already marked as sorted, 282 * does nothing. Adding or appending entries to the buffer will place the buffer 283 * back into an unsorted state. 284 */ 285ANDROID_API 286int sort_camera_metadata(camera_metadata_t *dst); 287 288/** 289 * Get metadata entry at position index in the metadata buffer. 290 * 291 * src and index are inputs; the passed-in entry is updated with the details of 292 * the entry. The data pointer points to the real data in the buffer, and can be 293 * updated as long as the data count does not change. 294 */ 295ANDROID_API 296int get_camera_metadata_entry(camera_metadata_t *src, 297 size_t index, 298 camera_metadata_entry_t *entry); 299 300/** 301 * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise, 302 * returns entry contents like get_camera_metadata_entry. 303 * 304 * If multiple entries with the same tag exist, does not have any guarantees on 305 * which is returned. To speed up searching for tags, sort the metadata 306 * structure first by calling sort_camera_metadata(). 307 */ 308ANDROID_API 309int find_camera_metadata_entry(camera_metadata_t *src, 310 uint32_t tag, 311 camera_metadata_entry_t *entry); 312 313/** 314 * Delete an entry at given index. This is an expensive operation, since it 315 * requires repacking entries and possibly entry data. This also invalidates any 316 * existing camera_metadata_entry.data pointers to this buffer. Sorting is 317 * maintained. 318 */ 319ANDROID_API 320int delete_camera_metadata_entry(camera_metadata_t *dst, 321 size_t index); 322 323/** 324 * Updates a metadata entry with new data. If the data size is changing, may 325 * need to adjust the data array, making this an O(N) operation. If the data 326 * size is the same or still fits in the entry space, this is O(1). Maintains 327 * sorting, but invalidates camera_metadata_entry instances that point to the 328 * updated entry. If a non-NULL value is passed in to entry, the entry structure 329 * is updated to match the new buffer state. Returns a non-zero value if there 330 * is no room for the new data in the buffer. 331 */ 332ANDROID_API 333int update_camera_metadata_entry(camera_metadata_t *dst, 334 size_t index, 335 const void *data, 336 size_t data_count, 337 camera_metadata_entry_t *updated_entry); 338 339/** 340 * Set user pointer in buffer. This can be used for linking the metadata buffer 341 * with other associated data. This user pointer is not copied with 342 * copy_camera_metadata, and is unaffected by append or any other methods. 343 */ 344ANDROID_API 345int set_camera_metadata_user_pointer(camera_metadata_t *dst, void* user); 346 347/** 348 * Retrieve user pointer in buffer. Returns NULL in user if 349 * set_camera_metadata_user_pointer has not been called with this buffer. 350 */ 351ANDROID_API 352int get_camera_metadata_user_pointer(camera_metadata_t *dst, void** user); 353 354/** 355 * Retrieve human-readable name of section the tag is in. Returns NULL if 356 * no such tag is defined. Returns NULL for tags in the vendor section, unless 357 * set_vendor_tag_query_ops() has been used. 358 */ 359ANDROID_API 360const char *get_camera_metadata_section_name(uint32_t tag); 361 362/** 363 * Retrieve human-readable name of tag (not including section). Returns NULL if 364 * no such tag is defined. Returns NULL for tags in the vendor section, unless 365 * set_vendor_tag_query_ops() has been used. 366 */ 367ANDROID_API 368const char *get_camera_metadata_tag_name(uint32_t tag); 369 370/** 371 * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1 372 * for tags in the vendor section, unless set_vendor_tag_query_ops() has been 373 * used. 374 */ 375ANDROID_API 376int get_camera_metadata_tag_type(uint32_t tag); 377 378/** 379 * Set up vendor-specific tag query methods. These are needed to properly add 380 * entries with vendor-specified tags and to use the 381 * get_camera_metadata_section_name, _tag_name, and _tag_type methods with 382 * vendor tags. Returns 0 on success. 383 */ 384typedef struct vendor_tag_query_ops vendor_tag_query_ops_t; 385struct vendor_tag_query_ops { 386 /** 387 * Get vendor section name for a vendor-specified entry tag. Only called for 388 * tags >= 0x80000000. The section name must start with the name of the 389 * vendor in the Java package style. For example, CameraZoom inc must prefix 390 * their sections with "com.camerazoom." Must return NULL if the tag is 391 * outside the bounds of vendor-defined sections. 392 */ 393 const char *(*get_camera_vendor_section_name)( 394 const vendor_tag_query_ops_t *v, 395 uint32_t tag); 396 /** 397 * Get tag name for a vendor-specified entry tag. Only called for tags >= 398 * 0x80000000. Must return NULL if the tag is outside the bounds of 399 * vendor-defined sections. 400 */ 401 const char *(*get_camera_vendor_tag_name)( 402 const vendor_tag_query_ops_t *v, 403 uint32_t tag); 404 /** 405 * Get tag type for a vendor-specified entry tag. Only called for tags >= 406 * 0x80000000. Must return -1 if the tag is outside the bounds of 407 * vendor-defined sections. 408 */ 409 int (*get_camera_vendor_tag_type)( 410 const vendor_tag_query_ops_t *v, 411 uint32_t tag); 412}; 413 414ANDROID_API 415int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops); 416 417/** 418 * Print fields in the metadata to the log. 419 * verbosity = 0: Only tag entry information 420 * verbosity = 1: Tag entry information plus at most 16 data values 421 * verbosity = 2: All information 422 */ 423ANDROID_API 424void dump_camera_metadata(const camera_metadata_t *metadata, 425 int fd, 426 int verbosity); 427 428/** 429 * Print fields in the metadata to the log; adds indentation parameter, which 430 * specifies the number of spaces to insert before each line of the dump 431 */ 432ANDROID_API 433void dump_indented_camera_metadata(const camera_metadata_t *metadata, 434 int fd, 435 int verbosity, 436 int indentation); 437 438#ifdef __cplusplus 439} 440#endif 441 442#endif 443