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