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 50 typedef struct ACameraOutputTargets ACameraOutputTargets; 51 52 // Container for a single output target 53 typedef 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 */ 84 typedef 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 */ 104 camera_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 */ 113 void 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 */ 125 camera_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 */ 140 camera_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 */ 160 camera_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 */ 181 camera_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 */ 200 camera_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 */ 219 camera_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 */ 238 camera_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 */ 257 camera_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 */ 276 camera_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 */ 295 camera_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 */ 304 void ACaptureRequest_free(ACaptureRequest* request); 305 306 #endif /* __ANDROID_API__ >= 24 */ 307 308 #if __ANDROID_API__ >= 28 309 310 /** 311 * Associate an arbitrary user context pointer to the {@link ACaptureRequest} 312 * 313 * This method is useful for user to identify the capture request in capture session callbacks. 314 * The context is NULL for newly created request. 315 * {@link ACameraOutputTarget_free} will not free the context. Also calling this method twice 316 * will not cause the previous context be freed. 317 * Also note that calling this method after the request has been sent to capture session will not 318 * change the context pointer in the capture callbacks. 319 * 320 * @param request the {@link ACaptureRequest} of interest. 321 * @param context the user context pointer to be associated with this capture request. 322 * 323 * @return <ul> 324 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 325 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL.</li></ul> 326 */ 327 camera_status_t ACaptureRequest_setUserContext( 328 ACaptureRequest* request, void* context); 329 330 /** 331 * Get the user context pointer of the {@link ACaptureRequest} 332 * 333 * This method is useful for user to identify the capture request in capture session callbacks. 334 * The context is NULL for newly created request. 335 * 336 * @param request the {@link ACaptureRequest} of interest. 337 * @param context the user context pointer of this capture request. 338 * 339 * @return <ul> 340 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 341 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL.</li></ul> 342 */ 343 camera_status_t ACaptureRequest_getUserContext( 344 const ACaptureRequest* request, /*out*/void** context); 345 346 /** 347 * Create a copy of input {@link ACaptureRequest}. 348 * 349 * <p>The returned ACaptureRequest must be freed by the application by {@link ACaptureRequest_free} 350 * after application is done using it.</p> 351 * 352 * @param src the input {@link ACaptureRequest} to be copied. 353 * 354 * @return a valid ACaptureRequest pointer or NULL if the input request cannot be copied. 355 */ 356 ACaptureRequest* ACaptureRequest_copy(const ACaptureRequest* src); 357 358 #endif /* __ANDROID_API__ >= 28 */ 359 360 __END_DECLS 361 362 #endif /* _NDK_CAPTURE_REQUEST_H */ 363 364 /** @} */ 365