camera_metadata.h revision d8afb4d1a4245b2a9d722cbb358a4d6febed89cf
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 * Size in bytes of each entry type 75 */ 76ANDROID_API 77extern size_t camera_metadata_type_sizes[NUM_TYPES]; 78 79/** 80 * Main definitions for the metadata entry and array structures 81 * ============================================================================= 82 */ 83 84/** 85 * A packet of metadata. This is a list of metadata entries, each of which has 86 * an integer tag to identify its meaning, 'type' and 'count' field, and the 87 * data, which contains a 'count' number of entries of type 'type'. The packet 88 * has a fixed capacity for entries and for extra data. A new entry uses up one 89 * entry slot, and possibly some amount of data capacity; the function 90 * calculate_camera_metadata_entry_data_size() provides the amount of data 91 * capacity that would be used up by an entry. 92 * 93 * Entries are not sorted, and are not forced to be unique - multiple entries 94 * with the same tag are allowed. The packet will not dynamically resize when 95 * full. 96 * 97 * The packet is contiguous in memory, with size in bytes given by 98 * get_camera_metadata_size(). Therefore, it can be copied safely with memcpy() 99 * to a buffer of sufficient size. The copy_camera_metadata() function is 100 * intended for eliminating unused capacity in the destination packet. 101 */ 102struct camera_metadata; 103typedef struct camera_metadata camera_metadata_t; 104 105/** 106 * Functions for manipulating camera metadata 107 * ============================================================================= 108 */ 109 110/** 111 * Allocate a new camera_metadata structure, with some initial space for entries 112 * and extra data. The entry_capacity is measured in entry counts, and 113 * data_capacity in bytes. The resulting structure is all contiguous in memory, 114 * and can be freed with free_camera_metadata(). 115 */ 116ANDROID_API 117camera_metadata_t *allocate_camera_metadata(size_t entry_capacity, 118 size_t data_capacity); 119 120/** 121 * Place a camera metadata structure into an existing buffer. Returns NULL if 122 * the buffer is too small for the requested number of reserved entries and 123 * bytes of data. The entry_capacity is measured in entry counts, and 124 * data_capacity in bytes. If the buffer is larger than the required space, 125 * unused space will be left at the end. If successful, returns a pointer to the 126 * metadata header placed at the start of the buffer. It is the caller's 127 * responsibility to free the original buffer; do not call 128 * free_camera_metadata() with the returned pointer. 129 */ 130ANDROID_API 131camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size, 132 size_t entry_capacity, 133 size_t data_capacity); 134 135/** 136 * Free a camera_metadata structure. Should only be used with structures 137 * allocated with allocate_camera_metadata(). 138 */ 139ANDROID_API 140void free_camera_metadata(camera_metadata_t *metadata); 141 142/** 143 * Calculate the buffer size needed for a metadata structure of entry_count 144 * metadata entries, needing a total of data_count bytes of extra data storage. 145 */ 146ANDROID_API 147size_t calculate_camera_metadata_size(size_t entry_count, 148 size_t data_count); 149 150/** 151 * Get current size of entire metadata structure in bytes, including reserved 152 * but unused space. 153 */ 154ANDROID_API 155size_t get_camera_metadata_size(const camera_metadata_t *metadata); 156 157/** 158 * Get size of entire metadata buffer in bytes, not including reserved but 159 * unused space. This is the amount of space needed by copy_camera_metadata for 160 * its dst buffer. 161 */ 162ANDROID_API 163size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata); 164 165/** 166 * Get the current number of entries in the metadata packet. 167 */ 168ANDROID_API 169size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata); 170 171/** 172 * Get the maximum number of entries that could fit in the metadata packet. 173 */ 174ANDROID_API 175size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata); 176 177/** 178 * Get the current count of bytes used for value storage in the metadata packet. 179 */ 180ANDROID_API 181size_t get_camera_metadata_data_count(const camera_metadata_t *metadata); 182 183/** 184 * Get the maximum count of bytes that could be used for value storage in the 185 * metadata packet. 186 */ 187ANDROID_API 188size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata); 189 190/** 191 * Copy a metadata structure to a memory buffer, compacting it along the 192 * way. That is, in the copied structure, entry_count == entry_capacity, and 193 * data_count == data_capacity. 194 * 195 * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the 196 * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns 197 * NULL. Otherwise returns a pointer to the metadata structure header placed at 198 * the start of dst. 199 * 200 * Since the buffer was not allocated by allocate_camera_metadata, the caller is 201 * responsible for freeing the underlying buffer when needed; do not call 202 * free_camera_metadata. 203 */ 204ANDROID_API 205camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size, 206 const camera_metadata_t *src); 207 208/** 209 * Append camera metadata in src to an existing metadata structure in dst. This 210 * does not resize the destination structure, so if it is too small, a non-zero 211 * value is returned. On success, 0 is returned. 212 */ 213ANDROID_API 214int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src); 215 216/** 217 * Calculate the number of bytes of extra data a given metadata entry will take 218 * up. That is, if entry of 'type' with a payload of 'data_count' values is 219 * added, how much will the value returned by get_camera_metadata_data_count() 220 * be increased? This value may be zero, if no extra data storage is needed. 221 */ 222ANDROID_API 223size_t calculate_camera_metadata_entry_data_size(uint8_t type, 224 size_t data_count); 225 226/** 227 * Add a metadata entry to a metadata structure. Returns 0 if the addition 228 * succeeded. Returns a non-zero value if there is insufficient reserved space 229 * left to add the entry, or if the tag is unknown. data_count is the number of 230 * entries in the data array of the tag's type, not a count of 231 * bytes. Vendor-defined tags can not be added using this method, unless 232 * set_vendor_tag_query_ops() has been called first. 233 */ 234ANDROID_API 235int add_camera_metadata_entry(camera_metadata_t *dst, 236 uint32_t tag, 237 const void *data, 238 size_t data_count); 239 240/** 241 * Get pointers to the fields for a metadata entry at position index in the 242 * entry array. The data pointer points either to the entry's data.value field 243 * or to the right offset in camera_metadata_t.data. Returns 0 on 244 * success. Data_count is the number of entries in the data array when cast to 245 * the tag's type, not a count of bytes. 246 * 247 * src and index are inputs; tag, type, data, and data_count are outputs. 248 */ 249ANDROID_API 250int get_camera_metadata_entry(camera_metadata_t *src, 251 uint32_t index, 252 uint32_t *tag, 253 uint8_t *type, 254 void **data, 255 size_t *data_count); 256 257/** 258 * Retrieve human-readable name of section the tag is in. Returns NULL if 259 * no such tag is defined. Returns NULL for tags in the vendor section, unless 260 * set_vendor_tag_query_ops() has been used. 261 */ 262ANDROID_API 263const char *get_camera_metadata_section_name(uint32_t tag); 264 265/** 266 * Retrieve human-readable name of tag (not including section). Returns NULL if 267 * no such tag is defined. Returns NULL for tags in the vendor section, unless 268 * set_vendor_tag_query_ops() has been used. 269 */ 270ANDROID_API 271const char *get_camera_metadata_tag_name(uint32_t tag); 272 273/** 274 * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1 275 * for tags in the vendor section, unless set_vendor_tag_query_ops() has been 276 * used. 277 */ 278ANDROID_API 279int get_camera_metadata_tag_type(uint32_t tag); 280 281/** 282 * Set up vendor-specific tag query methods. These are needed to properly add 283 * entries with vendor-specified tags and to use the 284 * get_camera_metadata_section_name, _tag_name, and _tag_type methods with 285 * vendor tags. Returns 0 on success. 286 */ 287typedef struct vendor_tag_query_ops { 288 /** 289 * Get vendor section name for a vendor-specified entry tag. Only called for 290 * tags >= 0x80000000. The section name must start with the name of the 291 * vendor in the Java package style. For example, CameraZoom inc must prefix 292 * their sections with "com.camerazoom." Must return NULL if the tag is 293 * outside the bounds of vendor-defined sections. 294 */ 295 const char *(*get_camera_vendor_section_name)(uint32_t tag); 296 /** 297 * Get tag name for a vendor-specified entry tag. Only called for tags >= 298 * 0x80000000. Must return NULL if the tag is outside the bounds of 299 * vendor-defined sections. 300 */ 301 const char *(*get_camera_vendor_tag_name)(uint32_t tag); 302 /** 303 * Get tag type for a vendor-specified entry tag. Only called for tags >= 304 * 0x80000000. Must return -1 if the tag is outside the bounds of 305 * vendor-defined sections. 306 */ 307 int (*get_camera_vendor_tag_type)(uint32_t tag); 308} vendor_tag_query_ops_t; 309 310ANDROID_API 311int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops); 312 313/** 314 * Print fields in the metadata to the log. 315 * verbosity = 0: Only tag entry information 316 * verbosity = 1: Tag entry information plus at most 16 data values 317 * verbosity = 2: All information 318 */ 319ANDROID_API 320void dump_camera_metadata(const camera_metadata_t *metadata, 321 int verbosity); 322 323#ifdef __cplusplus 324} 325#endif 326 327#endif 328