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 NdkCaptureRequest.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#include <sys/cdefs.h>
37
38#include <android/native_window.h>
39#include "NdkCameraError.h"
40#include "NdkCameraMetadata.h"
41
42#ifndef _NDK_CAPTURE_REQUEST_H
43#define _NDK_CAPTURE_REQUEST_H
44
45__BEGIN_DECLS
46
47#if __ANDROID_API__ >= 24
48
49// Container for output targets
50typedef struct ACameraOutputTargets ACameraOutputTargets;
51
52// Container for a single output target
53typedef struct ACameraOutputTarget ACameraOutputTarget;
54
55/**
56 * ACaptureRequest is an opaque type that contains settings and output targets needed to capture
57 * a single image from camera device.
58 *
59 * <p>ACaptureRequest contains the configuration for the capture hardware (sensor, lens, flash),
60 * the processing pipeline, the control algorithms, and the output buffers. Also
61 * contains the list of target {@link ANativeWindow}s to send image data to for this
62 * capture.</p>
63 *
64 * <p>ACaptureRequest is created by {@link ACameraDevice_createCaptureRequest}.
65 *
66 * <p>ACaptureRequest is given to {@link ACameraCaptureSession_capture} or
67 * {@link ACameraCaptureSession_setRepeatingRequest} to capture images from a camera.</p>
68 *
69 * <p>Each request can specify a different subset of target {@link ANativeWindow}s for the
70 * camera to send the captured data to. All the {@link ANativeWindow}s used in a request must
71 * be part of the {@link ANativeWindow} list given to the last call to
72 * {@link ACameraDevice_createCaptureSession}, when the request is submitted to the
73 * session.</p>
74 *
75 * <p>For example, a request meant for repeating preview might only include the
76 * {@link ANativeWindow} for the preview SurfaceView or SurfaceTexture, while a
77 * high-resolution still capture would also include a {@link ANativeWindow} from a
78 * {@link AImageReader} configured for high-resolution JPEG images.</p>
79 *
80 * @see ACameraDevice_createCaptureRequest
81 * @see ACameraCaptureSession_capture
82 * @see ACameraCaptureSession_setRepeatingRequest
83 */
84typedef struct ACaptureRequest ACaptureRequest;
85
86/**
87 * Create a ACameraOutputTarget object.
88 *
89 * <p>The ACameraOutputTarget is used in {@link ACaptureRequest_addTarget} method to add an output
90 * {@link ANativeWindow} to ACaptureRequest. Use {@link ACameraOutputTarget_free} to free the object
91 * and its memory after application no longer needs the {@link ACameraOutputTarget}.</p>
92 *
93 * @param window the {@link ANativeWindow} to be associated with the {@link ACameraOutputTarget}
94 * @param output the output {@link ACameraOutputTarget} will be stored here if the
95 *                  method call succeeds.
96 *
97 * @return <ul>
98 *         <li>{@link ACAMERA_OK} if the method call succeeds. The created ACameraOutputTarget will
99 *                                be filled in the output argument.</li>
100 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if window or output is NULL.</li></ul>
101 *
102 * @see ACaptureRequest_addTarget
103 */
104camera_status_t ACameraOutputTarget_create(ANativeWindow* window, ACameraOutputTarget** output);
105
106/**
107 * Free a ACameraOutputTarget object.
108 *
109 * @param output the {@link ACameraOutputTarget} to be freed.
110 *
111 * @see ACameraOutputTarget_create
112 */
113void ACameraOutputTarget_free(ACameraOutputTarget* output);
114
115/**
116 * Add an {@link ACameraOutputTarget} object to {@link ACaptureRequest}.
117 *
118 * @param request the {@link ACaptureRequest} of interest.
119 * @param output the output {@link ACameraOutputTarget} to be added to capture request.
120 *
121 * @return <ul>
122 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
123 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request or output is NULL.</li></ul>
124 */
125camera_status_t ACaptureRequest_addTarget(ACaptureRequest* request,
126        const ACameraOutputTarget* output);
127
128/**
129 * Remove an {@link ACameraOutputTarget} object from {@link ACaptureRequest}.
130 *
131 * <p>This method has no effect if the ACameraOutputTarget does not exist in ACaptureRequest.</p>
132 *
133 * @param request the {@link ACaptureRequest} of interest.
134 * @param output the output {@link ACameraOutputTarget} to be removed from capture request.
135 *
136 * @return <ul>
137 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
138 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request or output is NULL.</li></ul>
139 */
140camera_status_t ACaptureRequest_removeTarget(ACaptureRequest* request,
141        const ACameraOutputTarget* output);
142
143/**
144 * Get a metadata entry from input {@link ACaptureRequest}.
145 *
146 * <p>The memory of the data field in returned entry is managed by camera framework. Do not
147 * attempt to free it.</p>
148 *
149 * @param request the {@link ACaptureRequest} of interest.
150 * @param tag the tag value of the camera metadata entry to be get.
151 * @param entry the output {@link ACameraMetadata_const_entry} will be filled here if the method
152 *        call succeeeds.
153 *
154 * @return <ul>
155 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
156 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata or entry is NULL.</li>
157 *         <li>{@link ACAMERA_ERROR_METADATA_NOT_FOUND} if the capture request does not contain an
158 *             entry of input tag value.</li></ul>
159 */
160camera_status_t ACaptureRequest_getConstEntry(
161        const ACaptureRequest* request, uint32_t tag, ACameraMetadata_const_entry* entry);
162
163/*
164 * List all the entry tags in input {@link ACaptureRequest}.
165 *
166 * @param request the {@link ACaptureRequest} of interest.
167 * @param numEntries number of metadata entries in input {@link ACaptureRequest}
168 * @param tags the tag values of the metadata entries. Length of tags is returned in numEntries
169 *             argument. The memory is managed by ACaptureRequest itself and must NOT be free/delete
170 *             by application. Calling ACaptureRequest_setEntry_* methods will invalidate previous
171 *             output of ACaptureRequest_getAllTags. Do not access tags after calling
172 *             ACaptureRequest_setEntry_*. To get new list of tags after updating capture request,
173 *             application must call ACaptureRequest_getAllTags again. Do NOT access tags after
174 *             calling ACaptureRequest_free.
175 *
176 * @return <ul>
177 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
178 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request, numEntries or tags is NULL.</li>
179 *         <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
180 */
181camera_status_t ACaptureRequest_getAllTags(
182        const ACaptureRequest* request, /*out*/int32_t* numTags, /*out*/const uint32_t** tags);
183
184/**
185 * Set/change a camera capture control entry with unsigned 8 bits data type.
186 *
187 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
188 *
189 * @param request the {@link ACaptureRequest} of interest.
190 * @param tag the tag value of the camera metadata entry to be set.
191 * @param count number of elements to be set in data argument
192 * @param data the entries to be set/change in the capture request.
193 *
194 * @return <ul>
195 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
196 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
197 *             zero while data is NULL, the data type of the tag is not unsigned 8 bits, or
198 *             the tag is not controllable by application.</li></ul>
199 */
200camera_status_t ACaptureRequest_setEntry_u8(
201        ACaptureRequest* request, uint32_t tag, uint32_t count, const uint8_t* data);
202
203/**
204 * Set/change a camera capture control entry with signed 32 bits data type.
205 *
206 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
207 *
208 * @param request the {@link ACaptureRequest} of interest.
209 * @param tag the tag value of the camera metadata entry to be set.
210 * @param count number of elements to be set in data argument
211 * @param data the entries to be set/change in the capture request.
212 *
213 * @return <ul>
214 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
215 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
216 *             zero while data is NULL, the data type of the tag is not signed 32 bits, or
217 *             the tag is not controllable by application.</li></ul>
218 */
219camera_status_t ACaptureRequest_setEntry_i32(
220        ACaptureRequest* request, uint32_t tag, uint32_t count, const int32_t* data);
221
222/**
223 * Set/change a camera capture control entry with float data type.
224 *
225 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
226 *
227 * @param request the {@link ACaptureRequest} of interest.
228 * @param tag the tag value of the camera metadata entry to be set.
229 * @param count number of elements to be set in data argument
230 * @param data the entries to be set/change in the capture request.
231 *
232 * @return <ul>
233 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
234 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
235 *             zero while data is NULL, the data type of the tag is not float, or
236 *             the tag is not controllable by application.</li></ul>
237 */
238camera_status_t ACaptureRequest_setEntry_float(
239        ACaptureRequest* request, uint32_t tag, uint32_t count, const float* data);
240
241/**
242 * Set/change a camera capture control entry with signed 64 bits data type.
243 *
244 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
245 *
246 * @param request the {@link ACaptureRequest} of interest.
247 * @param tag the tag value of the camera metadata entry to be set.
248 * @param count number of elements to be set in data argument
249 * @param data the entries to be set/change in the capture request.
250 *
251 * @return <ul>
252 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
253 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
254 *             zero while data is NULL, the data type of the tag is not signed 64 bits, or
255 *             the tag is not controllable by application.</li></ul>
256 */
257camera_status_t ACaptureRequest_setEntry_i64(
258        ACaptureRequest* request, uint32_t tag, uint32_t count, const int64_t* data);
259
260/**
261 * Set/change a camera capture control entry with double data type.
262 *
263 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
264 *
265 * @param request the {@link ACaptureRequest} of interest.
266 * @param tag the tag value of the camera metadata entry to be set.
267 * @param count number of elements to be set in data argument
268 * @param data the entries to be set/change in the capture request.
269 *
270 * @return <ul>
271 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
272 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
273 *             zero while data is NULL, the data type of the tag is not double, or
274 *             the tag is not controllable by application.</li></ul>
275 */
276camera_status_t ACaptureRequest_setEntry_double(
277        ACaptureRequest* request, uint32_t tag, uint32_t count, const double* data);
278
279/**
280 * Set/change a camera capture control entry with rational data type.
281 *
282 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>
283 *
284 * @param request the {@link ACaptureRequest} of interest.
285 * @param tag the tag value of the camera metadata entry to be set.
286 * @param count number of elements to be set in data argument
287 * @param data the entries to be set/change in the capture request.
288 *
289 * @return <ul>
290 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
291 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than
292 *             zero while data is NULL, the data type of the tag is not rational, or
293 *             the tag is not controllable by application.</li></ul>
294 */
295camera_status_t ACaptureRequest_setEntry_rational(
296        ACaptureRequest* request, uint32_t tag, uint32_t count,
297        const ACameraMetadata_rational* data);
298
299/**
300 * Free a {@link ACaptureRequest} structure.
301 *
302 * @param request the {@link ACaptureRequest} to be freed.
303 */
304void ACaptureRequest_free(ACaptureRequest* request);
305
306#endif /* __ANDROID_API__ >= 24 */
307
308__END_DECLS
309
310#endif /* _NDK_CAPTURE_REQUEST_H */
311
312/** @} */
313