2 * Copyright (C) 2012 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_METADATA_H
18 #define SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_METADATA_H
22 #include <cutils/compiler.h>
29 * Tag hierarchy and enum definitions for camera_metadata_entry
30 * =============================================================================
34 * Main enum definitions are in a separate file to make it easy to
37 #include "camera_metadata_tags.h"
40 * Enum range for each top-level category
43 extern unsigned int camera_metadata_section_bounds[ANDROID_SECTION_COUNT][2];
45 extern const char *camera_metadata_section_names[ANDROID_SECTION_COUNT];
48 * Type definitions for camera_metadata_entry
49 * =============================================================================
52 // Unsigned 8-bit integer (uint8_t)
54 // Signed 32-bit integer (int32_t)
56 // 32-bit float (float)
58 // Signed 64-bit integer (int64_t)
60 // 64-bit float (double)
62 // A 64-bit fraction (camera_metadata_rational_t)
64 // Number of type fields
68 typedef struct camera_metadata_rational {
71 } camera_metadata_rational_t;
74 * A reference to a metadata entry in a buffer.
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.
80 typedef struct camera_metadata_entry {
91 camera_metadata_rational_t *r;
93 } camera_metadata_entry_t;
96 * Size in bytes of each entry type
99 extern const size_t camera_metadata_type_size[NUM_TYPES];
102 * Human-readable name of each entry type
105 extern const char* camera_metadata_type_names[NUM_TYPES];
108 * Main definitions for the metadata entry and array structures
109 * =============================================================================
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.
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
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.
130 struct camera_metadata;
131 typedef struct camera_metadata camera_metadata_t;
134 * Functions for manipulating camera metadata
135 * =============================================================================
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().
145 camera_metadata_t *allocate_camera_metadata(size_t entry_capacity,
146 size_t data_capacity);
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.
159 camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size,
160 size_t entry_capacity,
161 size_t data_capacity);
164 * Free a camera_metadata structure. Should only be used with structures
165 * allocated with allocate_camera_metadata().
168 void free_camera_metadata(camera_metadata_t *metadata);
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.
175 size_t calculate_camera_metadata_size(size_t entry_count,
179 * Get current size of entire metadata structure in bytes, including reserved
183 size_t get_camera_metadata_size(const camera_metadata_t *metadata);
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
191 size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata);
194 * Get the current number of entries in the metadata packet.
197 size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata);
200 * Get the maximum number of entries that could fit in the metadata packet.
203 size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata);
206 * Get the current count of bytes used for value storage in the metadata packet.
209 size_t get_camera_metadata_data_count(const camera_metadata_t *metadata);
212 * Get the maximum count of bytes that could be used for value storage in the
216 size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata);
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.
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
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.
233 camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size,
234 const camera_metadata_t *src);
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.
243 int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src);
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.
252 camera_metadata_t *clone_camera_metadata(camera_metadata_t *src);
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.
261 size_t calculate_camera_metadata_entry_data_size(uint8_t type,
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.
275 int add_camera_metadata_entry(camera_metadata_t *dst,
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.
286 int sort_camera_metadata(camera_metadata_t *dst);
289 * Get metadata entry at position index in the metadata buffer.
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.
296 int get_camera_metadata_entry(camera_metadata_t *src,
298 camera_metadata_entry_t *entry);
301 * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise,
302 * returns entry contents like get_camera_metadata_entry.
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().
309 int find_camera_metadata_entry(camera_metadata_t *src,
311 camera_metadata_entry_t *entry);
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
320 int delete_camera_metadata_entry(camera_metadata_t *dst,
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.
333 int update_camera_metadata_entry(camera_metadata_t *dst,
337 camera_metadata_entry_t *updated_entry);
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.
345 int set_camera_metadata_user_pointer(camera_metadata_t *dst, void* user);
348 * Retrieve user pointer in buffer. Returns NULL in user if
349 * set_camera_metadata_user_pointer has not been called with this buffer.
352 int get_camera_metadata_user_pointer(camera_metadata_t *dst, void** user);
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.
360 const char *get_camera_metadata_section_name(uint32_t tag);
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.
368 const char *get_camera_metadata_tag_name(uint32_t tag);
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
376 int get_camera_metadata_tag_type(uint32_t tag);
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.
384 typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
385 struct vendor_tag_query_ops {
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.
393 const char *(*get_camera_vendor_section_name)(
394 const vendor_tag_query_ops_t *v,
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.
401 const char *(*get_camera_vendor_tag_name)(
402 const vendor_tag_query_ops_t *v,
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.
409 int (*get_camera_vendor_tag_type)(
410 const vendor_tag_query_ops_t *v,
415 int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops);
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
424 void dump_camera_metadata(const camera_metadata_t *metadata,
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
433 void dump_indented_camera_metadata(const camera_metadata_t *metadata,