camera/include/system/camera_metadata.h

   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_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H
  18 #define SYSTEM_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H
  19
  20 #include <string.h>
  21 #include <stdint.h>
  22 #include <cutils/compiler.h>
  23
  24 #ifdef __cplusplus
  25 extern "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  */
  42 ANDROID_API
  43 extern unsigned int camera_metadata_section_bounds[ANDROID_SECTION_COUNT][2];
  44 ANDROID_API
  45 extern const char *camera_metadata_section_names[ANDROID_SECTION_COUNT];
  46
  47 /**
  48  * Type definitions for camera_metadata_entry
  49  * =============================================================================
  50  */
  51 enum {
  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
  68 typedef 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  */
  80 typedef 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  * A read-only reference to a metadata entry in a buffer. Identical to
  97  * camera_metadata_entry in layout
  98  */
  99 typedef struct camera_metadata_ro_entry {
 100     size_t   index;
 101     uint32_t tag;
 102     uint8_t  type;
 103     size_t   count;
 104     union {
 105         const uint8_t *u8;
 106         const int32_t *i32;
 107         const float   *f;
 108         const int64_t *i64;
 109         const double  *d;
 110         const camera_metadata_rational_t *r;
 111     } data;
 112 } camera_metadata_ro_entry_t;
 113
 114 /**
 115  * Size in bytes of each entry type
 116  */
 117 ANDROID_API
 118 extern const size_t camera_metadata_type_size[NUM_TYPES];
 119
 120 /**
 121  * Human-readable name of each entry type
 122  */
 123 ANDROID_API
 124 extern const char* camera_metadata_type_names[NUM_TYPES];
 125
 126 /**
 127  * Main definitions for the metadata entry and array structures
 128  * =============================================================================
 129  */
 130
 131 /**
 132  * A packet of metadata. This is a list of metadata entries, each of which has
 133  * an integer tag to identify its meaning, 'type' and 'count' field, and the
 134  * data, which contains a 'count' number of entries of type 'type'. The packet
 135  * has a fixed capacity for entries and for extra data.  A new entry uses up one
 136  * entry slot, and possibly some amount of data capacity; the function
 137  * calculate_camera_metadata_entry_data_size() provides the amount of data
 138  * capacity that would be used up by an entry.
 139  *
 140  * Entries are not sorted by default, and are not forced to be unique - multiple
 141  * entries with the same tag are allowed. The packet will not dynamically resize
 142  * when full.
 143  *
 144  * The packet is contiguous in memory, with size in bytes given by
 145  * get_camera_metadata_size(). Therefore, it can be copied safely with memcpy()
 146  * to a buffer of sufficient size. The copy_camera_metadata() function is
 147  * intended for eliminating unused capacity in the destination packet.
 148  */
 149 struct camera_metadata;
 150 typedef struct camera_metadata camera_metadata_t;
 151
 152 /**
 153  * Functions for manipulating camera metadata
 154  * =============================================================================
 155  *
 156  * NOTE: Unless otherwise specified, functions that return type "int"
 157  * return 0 on success, and non-0 value on error.
 158  */
 159
 160 /**
 161  * Allocate a new camera_metadata structure, with some initial space for entries
 162  * and extra data. The entry_capacity is measured in entry counts, and
 163  * data_capacity in bytes. The resulting structure is all contiguous in memory,
 164  * and can be freed with free_camera_metadata().
 165  */
 166 ANDROID_API
 167 camera_metadata_t *allocate_camera_metadata(size_t entry_capacity,
 168         size_t data_capacity);
 169
 170 /**
 171  * Get the required alignment of a packet of camera metadata, which is the
 172  * maximal alignment of the embedded camera_metadata, camera_metadata_buffer_entry,
 173  * and camera_metadata_data.
 174  */
 175 ANDROID_API
 176 size_t get_camera_metadata_alignment();
 177
 178 /**
 179  * Allocate a new camera_metadata structure of size src_size. Copy the data,
 180  * ignoring alignment, and then attempt validation. If validation
 181  * fails, free the memory and return NULL. Otherwise return the pointer.
 182  *
 183  * The resulting pointer can be freed with free_camera_metadata().
 184  */
 185 ANDROID_API
 186 camera_metadata_t *allocate_copy_camera_metadata_checked(
 187         const camera_metadata_t *src,
 188         size_t src_size);
 189
 190 /**
 191  * Place a camera metadata structure into an existing buffer. Returns NULL if
 192  * the buffer is too small for the requested number of reserved entries and
 193  * bytes of data. The entry_capacity is measured in entry counts, and
 194  * data_capacity in bytes. If the buffer is larger than the required space,
 195  * unused space will be left at the end. If successful, returns a pointer to the
 196  * metadata header placed at the start of the buffer. It is the caller's
 197  * responsibility to free the original buffer; do not call
 198  * free_camera_metadata() with the returned pointer.
 199  */
 200 ANDROID_API
 201 camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size,
 202         size_t entry_capacity,
 203         size_t data_capacity);
 204
 205 /**
 206  * Free a camera_metadata structure. Should only be used with structures
 207  * allocated with allocate_camera_metadata().
 208  */
 209 ANDROID_API
 210 void free_camera_metadata(camera_metadata_t *metadata);
 211
 212 /**
 213  * Calculate the buffer size needed for a metadata structure of entry_count
 214  * metadata entries, needing a total of data_count bytes of extra data storage.
 215  */
 216 ANDROID_API
 217 size_t calculate_camera_metadata_size(size_t entry_count,
 218         size_t data_count);
 219
 220 /**
 221  * Get current size of entire metadata structure in bytes, including reserved
 222  * but unused space.
 223  */
 224 ANDROID_API
 225 size_t get_camera_metadata_size(const camera_metadata_t *metadata);
 226
 227 /**
 228  * Get size of entire metadata buffer in bytes, not including reserved but
 229  * unused space. This is the amount of space needed by copy_camera_metadata for
 230  * its dst buffer.
 231  */
 232 ANDROID_API
 233 size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata);
 234
 235 /**
 236  * Get the current number of entries in the metadata packet.
 237  *
 238  * metadata packet must be valid, which can be checked before the call with
 239  * validate_camera_metadata_structure().
 240  */
 241 ANDROID_API
 242 size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata);
 243
 244 /**
 245  * Get the maximum number of entries that could fit in the metadata packet.
 246  */
 247 ANDROID_API
 248 size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata);
 249
 250 /**
 251  * Get the current count of bytes used for value storage in the metadata packet.
 252  */
 253 ANDROID_API
 254 size_t get_camera_metadata_data_count(const camera_metadata_t *metadata);
 255
 256 /**
 257  * Get the maximum count of bytes that could be used for value storage in the
 258  * metadata packet.
 259  */
 260 ANDROID_API
 261 size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata);
 262
 263 /**
 264  * Copy a metadata structure to a memory buffer, compacting it along the
 265  * way. That is, in the copied structure, entry_count == entry_capacity, and
 266  * data_count == data_capacity.
 267  *
 268  * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the
 269  * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns
 270  * NULL. Otherwise returns a pointer to the metadata structure header placed at
 271  * the start of dst.
 272  *
 273  * Since the buffer was not allocated by allocate_camera_metadata, the caller is
 274  * responsible for freeing the underlying buffer when needed; do not call
 275  * free_camera_metadata.
 276  */
 277 ANDROID_API
 278 camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size,
 279         const camera_metadata_t *src);
 280
 281
 282 // Non-zero return values for validate_camera_metadata_structure
 283 enum {
 284     CAMERA_METADATA_VALIDATION_ERROR = 1,
 285     CAMERA_METADATA_VALIDATION_SHIFTED = 2,
 286 };
 287
 288 /**
 289  * Validate that a metadata is structurally sane. That is, its internal
 290  * state is such that we won't get buffer overflows or run into other
 291  * 'impossible' issues when calling the other API functions.
 292  *
 293  * This is useful in particular after copying the binary metadata blob
 294  * from an untrusted source, since passing this check means the data is at least
 295  * consistent.
 296  *
 297  * The expected_size argument is optional.
 298  *
 299  * Returns 0: on success
 300  *         CAMERA_METADATA_VALIDATION_ERROR: on error
 301  *         CAMERA_METADATA_VALIDATION_SHIFTED: when the data is not properly aligned, but can be
 302  *                 used as input of clone_camera_metadata and the returned metadata will be valid.
 303  *
 304  */
 305 ANDROID_API
 306 int validate_camera_metadata_structure(const camera_metadata_t *metadata,
 307                                        const size_t *expected_size);
 308
 309 /**
 310  * Append camera metadata in src to an existing metadata structure in dst.  This
 311  * does not resize the destination structure, so if it is too small, a non-zero
 312  * value is returned. On success, 0 is returned. Appending onto a sorted
 313  * structure results in a non-sorted combined structure.
 314  */
 315 ANDROID_API
 316 int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src);
 317
 318 /**
 319  * Clone an existing metadata buffer, compacting along the way. This is
 320  * equivalent to allocating a new buffer of the minimum needed size, then
 321  * appending the buffer to be cloned into the new buffer. The resulting buffer
 322  * can be freed with free_camera_metadata(). Returns NULL if cloning failed.
 323  */
 324 ANDROID_API
 325 camera_metadata_t *clone_camera_metadata(const camera_metadata_t *src);
 326
 327 /**
 328  * Calculate the number of bytes of extra data a given metadata entry will take
 329  * up. That is, if entry of 'type' with a payload of 'data_count' values is
 330  * added, how much will the value returned by get_camera_metadata_data_count()
 331  * be increased? This value may be zero, if no extra data storage is needed.
 332  */
 333 ANDROID_API
 334 size_t calculate_camera_metadata_entry_data_size(uint8_t type,
 335         size_t data_count);
 336
 337 /**
 338  * Add a metadata entry to a metadata structure. Returns 0 if the addition
 339  * succeeded. Returns a non-zero value if there is insufficient reserved space
 340  * left to add the entry, or if the tag is unknown.  data_count is the number of
 341  * entries in the data array of the tag's type, not a count of
 342  * bytes. Vendor-defined tags can not be added using this method, unless
 343  * set_vendor_tag_query_ops() has been called first. Entries are always added to
 344  * the end of the structure (highest index), so after addition, a
 345  * previously-sorted array will be marked as unsorted.
 346  *
 347  * Returns 0 on success. A non-0 value is returned on error.
 348  */
 349 ANDROID_API
 350 int add_camera_metadata_entry(camera_metadata_t *dst,
 351         uint32_t tag,
 352         const void *data,
 353         size_t data_count);
 354
 355 /**
 356  * Sort the metadata buffer for fast searching. If already marked as sorted,
 357  * does nothing. Adding or appending entries to the buffer will place the buffer
 358  * back into an unsorted state.
 359  *
 360  * Returns 0 on success. A non-0 value is returned on error.
 361  */
 362 ANDROID_API
 363 int sort_camera_metadata(camera_metadata_t *dst);
 364
 365 /**
 366  * Get metadata entry at position index in the metadata buffer.
 367  * Index must be less than entry count, which is returned by
 368  * get_camera_metadata_entry_count().
 369  *
 370  * src and index are inputs; the passed-in entry is updated with the details of
 371  * the entry. The data pointer points to the real data in the buffer, and can be
 372  * updated as long as the data count does not change.
 373  *
 374  * Returns 0 on success. A non-0 value is returned on error.
 375  */
 376 ANDROID_API
 377 int get_camera_metadata_entry(camera_metadata_t *src,
 378         size_t index,
 379         camera_metadata_entry_t *entry);
 380
 381 /**
 382  * Get metadata entry at position index, but disallow editing the data.
 383  */
 384 ANDROID_API
 385 int get_camera_metadata_ro_entry(const camera_metadata_t *src,
 386         size_t index,
 387         camera_metadata_ro_entry_t *entry);
 388
 389 /**
 390  * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise,
 391  * returns entry contents like get_camera_metadata_entry.
 392  *
 393  * If multiple entries with the same tag exist, does not have any guarantees on
 394  * which is returned. To speed up searching for tags, sort the metadata
 395  * structure first by calling sort_camera_metadata().
 396  */
 397 ANDROID_API
 398 int find_camera_metadata_entry(camera_metadata_t *src,
 399         uint32_t tag,
 400         camera_metadata_entry_t *entry);
 401
 402 /**
 403  * Find an entry with given tag value, but disallow editing the data
 404  */
 405 ANDROID_API
 406 int find_camera_metadata_ro_entry(const camera_metadata_t *src,
 407         uint32_t tag,
 408         camera_metadata_ro_entry_t *entry);
 409
 410 /**
 411  * Delete an entry at given index. This is an expensive operation, since it
 412  * requires repacking entries and possibly entry data. This also invalidates any
 413  * existing camera_metadata_entry.data pointers to this buffer. Sorting is
 414  * maintained.
 415  */
 416 ANDROID_API
 417 int delete_camera_metadata_entry(camera_metadata_t *dst,
 418         size_t index);
 419
 420 /**
 421  * Updates a metadata entry with new data. If the data size is changing, may
 422  * need to adjust the data array, making this an O(N) operation. If the data
 423  * size is the same or still fits in the entry space, this is O(1). Maintains
 424  * sorting, but invalidates camera_metadata_entry instances that point to the
 425  * updated entry. If a non-NULL value is passed in to entry, the entry structure
 426  * is updated to match the new buffer state.  Returns a non-zero value if there
 427  * is no room for the new data in the buffer.
 428  */
 429 ANDROID_API
 430 int update_camera_metadata_entry(camera_metadata_t *dst,
 431         size_t index,
 432         const void *data,
 433         size_t data_count,
 434         camera_metadata_entry_t *updated_entry);
 435
 436 /**
 437  * Retrieve human-readable name of section the tag is in. Returns NULL if
 438  * no such tag is defined. Returns NULL for tags in the vendor section, unless
 439  * set_vendor_tag_query_ops() has been used.
 440  */
 441 ANDROID_API
 442 const char *get_camera_metadata_section_name(uint32_t tag);
 443
 444 /**
 445  * Retrieve human-readable name of tag (not including section). Returns NULL if
 446  * no such tag is defined. Returns NULL for tags in the vendor section, unless
 447  * set_vendor_tag_query_ops() has been used.
 448  */
 449 ANDROID_API
 450 const char *get_camera_metadata_tag_name(uint32_t tag);
 451
 452 /**
 453  * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1
 454  * for tags in the vendor section, unless set_vendor_tag_query_ops() has been
 455  * used.
 456  */
 457 ANDROID_API
 458 int get_camera_metadata_tag_type(uint32_t tag);
 459
 460 /**
 461  * Retrieve human-readable name of section the tag is in. Returns NULL if
 462  * no such tag is defined.
 463  */
 464 ANDROID_API
 465 const char *get_local_camera_metadata_section_name(uint32_t tag,
 466         const camera_metadata_t *meta);
 467
 468 /**
 469  * Retrieve human-readable name of tag (not including section). Returns NULL if
 470  * no such tag is defined.
 471  */
 472 ANDROID_API
 473 const char *get_local_camera_metadata_tag_name(uint32_t tag,
 474         const camera_metadata_t *meta);
 475
 476 /**
 477  * Retrieve the type of a tag. Returns -1 if no such tag is defined.
 478  */
 479 ANDROID_API
 480 int get_local_camera_metadata_tag_type(uint32_t tag,
 481         const camera_metadata_t *meta);
 482
 483 /**
 484  * Set up vendor-specific tag query methods. These are needed to properly add
 485  * entries with vendor-specified tags and to use the
 486  * get_camera_metadata_section_name, _tag_name, and _tag_type methods with
 487  * vendor tags. Returns 0 on success.
 488  *
 489  * **DEPRECATED** - Please use vendor_tag_ops defined in camera_vendor_tags.h
 490  *        instead.
 491  */
 492 typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
 493 struct vendor_tag_query_ops {
 494     /**
 495      * Get vendor section name for a vendor-specified entry tag. Only called for
 496      * tags >= 0x80000000. The section name must start with the name of the
 497      * vendor in the Java package style. For example, CameraZoom inc must prefix
 498      * their sections with "com.camerazoom." Must return NULL if the tag is
 499      * outside the bounds of vendor-defined sections.
 500      */
 501     const char *(*get_camera_vendor_section_name)(
 502         const vendor_tag_query_ops_t *v,
 503         uint32_t tag);
 504     /**
 505      * Get tag name for a vendor-specified entry tag. Only called for tags >=
 506      * 0x80000000. Must return NULL if the tag is outside the bounds of
 507      * vendor-defined sections.
 508      */
 509     const char *(*get_camera_vendor_tag_name)(
 510         const vendor_tag_query_ops_t *v,
 511         uint32_t tag);
 512     /**
 513      * Get tag type for a vendor-specified entry tag. Only called for tags >=
 514      * 0x80000000. Must return -1 if the tag is outside the bounds of
 515      * vendor-defined sections.
 516      */
 517     int (*get_camera_vendor_tag_type)(
 518         const vendor_tag_query_ops_t *v,
 519         uint32_t tag);
 520     /**
 521      * Get the number of vendor tags supported on this platform. Used to
 522      * calculate the size of buffer needed for holding the array of all tags
 523      * returned by get_camera_vendor_tags().
 524      */
 525     int (*get_camera_vendor_tag_count)(
 526         const vendor_tag_query_ops_t *v);
 527     /**
 528      * Fill an array with all the supported vendor tags on this platform.
 529      * get_camera_vendor_tag_count() returns the number of tags supported, and
 530      * tag_array should be allocated with enough space to hold all of the tags.
 531      */
 532     void (*get_camera_vendor_tags)(
 533         const vendor_tag_query_ops_t *v,
 534         uint32_t *tag_array);
 535 };
 536
 537 /**
 538  * **DEPRECATED** - This should only be used by the camera framework. Camera
 539  *      metadata will transition to using vendor_tag_ops defined in
 540  *      camera_vendor_tags.h instead.
 541  */
 542 ANDROID_API
 543 int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops);
 544
 545 /**
 546  * Print fields in the metadata to the log.
 547  * verbosity = 0: Only tag entry information
 548  * verbosity = 1: Tag entry information plus at most 16 data values
 549  * verbosity = 2: All information
 550  */
 551 ANDROID_API
 552 void dump_camera_metadata(const camera_metadata_t *metadata,
 553         int fd,
 554         int verbosity);
 555
 556 /**
 557  * Print fields in the metadata to the log; adds indentation parameter, which
 558  * specifies the number of spaces to insert before each line of the dump
 559  */
 560 ANDROID_API
 561 void dump_indented_camera_metadata(const camera_metadata_t *metadata,
 562         int fd,
 563         int verbosity,
 564         int indentation);
 565
 566 /**
 567  * Prints the specified tag value as a string. Only works for enum tags.
 568  * Returns 0 on success, -1 on failure.
 569  */
 570 ANDROID_API
 571 int camera_metadata_enum_snprint(uint32_t tag,
 572                                  uint32_t value,
 573                                  char *dst,
 574                                  size_t size);
 575
 576 #ifdef __cplusplus
 577 }
 578 #endif
 579
 580 #endif