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