blob: cd0b11ef6182f55a93658b1bd65755373df4574b [file] [log] [blame]
Yin-Chia Yehc3603822016-01-18 22:11:19 -08001/*
2 * Copyright (C) 2016 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
Yin-Chia Yeh3e49be12016-04-12 16:00:33 -070017/**
18 * @addtogroup Media Camera
19 * @{
20 */
21
22/**
23 * @file NdkImage.h
24 */
25
Yin-Chia Yehc3603822016-01-18 22:11:19 -080026/*
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_IMAGE_H
37#define _NDK_IMAGE_H
38
39#include "NdkMediaError.h"
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -070045/**
46 * AImage is an opaque type that provides access to image generated by {@link AImageReader}.
47 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -080048typedef struct AImage AImage;
49
50// Formats not listed here will not be supported by AImageReader
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -070051enum AIMAGE_FORMATS {
52 /**
53 * Multi-plane Android YUV 420 format.
54 *
55 * <p>This format is a generic YCbCr format, capable of describing any 4:2:0
56 * chroma-subsampled planar or semiplanar buffer (but not fully interleaved),
57 * with 8 bits per color sample.</p>
58 *
59 * <p>Images in this format are always represented by three separate buffers
60 * of data, one for each color plane. Additional information always
61 * accompanies the buffers, describing the row stride and the pixel stride
62 * for each plane.</p>
63 *
64 * <p>The order of planes is guaranteed such that plane #0 is always Y, plane #1 is always
65 * U (Cb), and plane #2 is always V (Cr).</p>
66 *
67 * <p>The Y-plane is guaranteed not to be interleaved with the U/V planes
68 * (in particular, pixel stride is always 1 in {@link AImage_getPlanePixelStride}).</p>
69 *
70 * <p>The U/V planes are guaranteed to have the same row stride and pixel stride, that is, the
71 * return value of {@link AImage_getPlaneRowStride} for the U/V plane are guaranteed to be the
72 * same, and the return value of {@link AImage_getPlanePixelStride} for the U/V plane are also
73 * guaranteed to be the same.</p>
74 *
75 * <p>For example, the {@link AImage} object can provide data
76 * in this format from a {@link ACameraDevice} through an {@link AImageReader} object.</p>
77 *
78 * <p>This format is always supported as an output format for the android Camera2 NDK API.</p>
79 *
80 * @see AImage
81 * @see AImageReader
82 * @see ACameraDevice
83 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -080084 AIMAGE_FORMAT_YUV_420_888 = 0x23,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -070085
86 /**
87 * Compressed JPEG format.
88 *
89 * <p>This format is always supported as an output format for the android Camera2 NDK API.</p>
90 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -080091 AIMAGE_FORMAT_JPEG = 0x100,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -070092
93 /**
94 * 16 bits per pixel raw camera sensor image format, usually representing a single-channel
95 * Bayer-mosaic image.
96 *
97 * <p>The layout of the color mosaic, the maximum and minimum encoding
98 * values of the raw pixel data, the color space of the image, and all other
99 * needed information to interpret a raw sensor image must be queried from
100 * the {@link ACameraDevice} which produced the image.</p>
101 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800102 AIMAGE_FORMAT_RAW16 = 0x20,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700103
104 /**
105 * Private raw camera sensor image format, a single channel image with implementation depedent
106 * pixel layout.
107 *
108 * <p>AIMAGE_FORMAT_RAW_PRIVATE is a format for unprocessed raw image buffers coming from an
109 * image sensor. The actual structure of buffers of this format is implementation-dependent.</p>
110 *
111 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800112 AIMAGE_FORMAT_RAW_PRIVATE = 0x24,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700113
114 /**
115 * Android 10-bit raw format.
116 *
117 * <p>
118 * This is a single-plane, 10-bit per pixel, densely packed (in each row),
119 * unprocessed format, usually representing raw Bayer-pattern images coming
120 * from an image sensor.
121 * </p>
122 * <p>
123 * In an image buffer with this format, starting from the first pixel of
124 * each row, each 4 consecutive pixels are packed into 5 bytes (40 bits).
125 * Each one of the first 4 bytes contains the top 8 bits of each pixel, The
126 * fifth byte contains the 2 least significant bits of the 4 pixels, the
127 * exact layout data for each 4 consecutive pixels is illustrated below
128 * (Pi[j] stands for the jth bit of the ith pixel):
129 * </p>
130 * <table>
131 * <tr>
132 * <th align="center"></th>
133 * <th align="center">bit 7</th>
134 * <th align="center">bit 6</th>
135 * <th align="center">bit 5</th>
136 * <th align="center">bit 4</th>
137 * <th align="center">bit 3</th>
138 * <th align="center">bit 2</th>
139 * <th align="center">bit 1</th>
140 * <th align="center">bit 0</th>
141 * </tr>
142 * <tr>
143 * <td align="center">Byte 0:</td>
144 * <td align="center">P0[9]</td>
145 * <td align="center">P0[8]</td>
146 * <td align="center">P0[7]</td>
147 * <td align="center">P0[6]</td>
148 * <td align="center">P0[5]</td>
149 * <td align="center">P0[4]</td>
150 * <td align="center">P0[3]</td>
151 * <td align="center">P0[2]</td>
152 * </tr>
153 * <tr>
154 * <td align="center">Byte 1:</td>
155 * <td align="center">P1[9]</td>
156 * <td align="center">P1[8]</td>
157 * <td align="center">P1[7]</td>
158 * <td align="center">P1[6]</td>
159 * <td align="center">P1[5]</td>
160 * <td align="center">P1[4]</td>
161 * <td align="center">P1[3]</td>
162 * <td align="center">P1[2]</td>
163 * </tr>
164 * <tr>
165 * <td align="center">Byte 2:</td>
166 * <td align="center">P2[9]</td>
167 * <td align="center">P2[8]</td>
168 * <td align="center">P2[7]</td>
169 * <td align="center">P2[6]</td>
170 * <td align="center">P2[5]</td>
171 * <td align="center">P2[4]</td>
172 * <td align="center">P2[3]</td>
173 * <td align="center">P2[2]</td>
174 * </tr>
175 * <tr>
176 * <td align="center">Byte 3:</td>
177 * <td align="center">P3[9]</td>
178 * <td align="center">P3[8]</td>
179 * <td align="center">P3[7]</td>
180 * <td align="center">P3[6]</td>
181 * <td align="center">P3[5]</td>
182 * <td align="center">P3[4]</td>
183 * <td align="center">P3[3]</td>
184 * <td align="center">P3[2]</td>
185 * </tr>
186 * <tr>
187 * <td align="center">Byte 4:</td>
188 * <td align="center">P3[1]</td>
189 * <td align="center">P3[0]</td>
190 * <td align="center">P2[1]</td>
191 * <td align="center">P2[0]</td>
192 * <td align="center">P1[1]</td>
193 * <td align="center">P1[0]</td>
194 * <td align="center">P0[1]</td>
195 * <td align="center">P0[0]</td>
196 * </tr>
197 * </table>
198 * <p>
199 * This format assumes
200 * <ul>
201 * <li>a width multiple of 4 pixels</li>
202 * <li>an even height</li>
203 * </ul>
204 * </p>
205 *
206 * <pre>size = row stride * height</pre> where the row stride is in <em>bytes</em>,
207 * not pixels.
208 *
209 * <p>
210 * Since this is a densely packed format, the pixel stride is always 0. The
211 * application must use the pixel data layout defined in above table to
212 * access each row data. When row stride is equal to (width * (10 / 8)), there
213 * will be no padding bytes at the end of each row, the entire image data is
214 * densely packed. When stride is larger than (width * (10 / 8)), padding
215 * bytes will be present at the end of each row.
216 * </p>
217 * <p>
218 * For example, the {@link AImage} object can provide data in this format from a
219 * {@link ACameraDevice} (if supported) through a {@link AImageReader} object.
220 * The number of planes returned by {@link AImage_getNumberOfPlanes} will always be 1.
221 * The pixel stride is undefined ({@link AImage_getPlanePixelStride} will return
222 * {@link AMEDIA_ERROR_UNSUPPORTED}), and the {@link AImage_getPlaneRowStride} described the
223 * vertical neighboring pixel distance (in bytes) between adjacent rows.
224 * </p>
225 *
226 * @see AImage
227 * @see AImageReader
228 * @see ACameraDevice
229 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800230 AIMAGE_FORMAT_RAW10 = 0x25,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700231
232 /**
233 * Android 12-bit raw format.
234 *
235 * <p>
236 * This is a single-plane, 12-bit per pixel, densely packed (in each row),
237 * unprocessed format, usually representing raw Bayer-pattern images coming
238 * from an image sensor.
239 * </p>
240 * <p>
241 * In an image buffer with this format, starting from the first pixel of each
242 * row, each two consecutive pixels are packed into 3 bytes (24 bits). The first
243 * and second byte contains the top 8 bits of first and second pixel. The third
244 * byte contains the 4 least significant bits of the two pixels, the exact layout
245 * data for each two consecutive pixels is illustrated below (Pi[j] stands for
246 * the jth bit of the ith pixel):
247 * </p>
248 * <table>
249 * <tr>
250 * <th align="center"></th>
251 * <th align="center">bit 7</th>
252 * <th align="center">bit 6</th>
253 * <th align="center">bit 5</th>
254 * <th align="center">bit 4</th>
255 * <th align="center">bit 3</th>
256 * <th align="center">bit 2</th>
257 * <th align="center">bit 1</th>
258 * <th align="center">bit 0</th>
259 * </tr>
260 * <tr>
261 * <td align="center">Byte 0:</td>
262 * <td align="center">P0[11]</td>
263 * <td align="center">P0[10]</td>
264 * <td align="center">P0[ 9]</td>
265 * <td align="center">P0[ 8]</td>
266 * <td align="center">P0[ 7]</td>
267 * <td align="center">P0[ 6]</td>
268 * <td align="center">P0[ 5]</td>
269 * <td align="center">P0[ 4]</td>
270 * </tr>
271 * <tr>
272 * <td align="center">Byte 1:</td>
273 * <td align="center">P1[11]</td>
274 * <td align="center">P1[10]</td>
275 * <td align="center">P1[ 9]</td>
276 * <td align="center">P1[ 8]</td>
277 * <td align="center">P1[ 7]</td>
278 * <td align="center">P1[ 6]</td>
279 * <td align="center">P1[ 5]</td>
280 * <td align="center">P1[ 4]</td>
281 * </tr>
282 * <tr>
283 * <td align="center">Byte 2:</td>
284 * <td align="center">P1[ 3]</td>
285 * <td align="center">P1[ 2]</td>
286 * <td align="center">P1[ 1]</td>
287 * <td align="center">P1[ 0]</td>
288 * <td align="center">P0[ 3]</td>
289 * <td align="center">P0[ 2]</td>
290 * <td align="center">P0[ 1]</td>
291 * <td align="center">P0[ 0]</td>
292 * </tr>
293 * </table>
294 * <p>
295 * This format assumes
296 * <ul>
297 * <li>a width multiple of 4 pixels</li>
298 * <li>an even height</li>
299 * </ul>
300 * </p>
301 *
302 * <pre>size = row stride * height</pre> where the row stride is in <em>bytes</em>,
303 * not pixels.
304 *
305 * <p>
306 * Since this is a densely packed format, the pixel stride is always 0. The
307 * application must use the pixel data layout defined in above table to
308 * access each row data. When row stride is equal to (width * (12 / 8)), there
309 * will be no padding bytes at the end of each row, the entire image data is
310 * densely packed. When stride is larger than (width * (12 / 8)), padding
311 * bytes will be present at the end of each row.
312 * </p>
313 * <p>
314 * For example, the {@link AImage} object can provide data in this format from a
315 * {@link ACameraDevice} (if supported) through a {@link AImageReader} object.
316 * The number of planes returned by {@link AImage_getNumberOfPlanes} will always be 1.
317 * The pixel stride is undefined ({@link AImage_getPlanePixelStride} will return
318 * {@link AMEDIA_ERROR_UNSUPPORTED}), and the {@link AImage_getPlaneRowStride} described the
319 * vertical neighboring pixel distance (in bytes) between adjacent rows.
320 * </p>
321 *
322 * @see AImage
323 * @see AImageReader
324 * @see ACameraDevice
325 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800326 AIMAGE_FORMAT_RAW12 = 0x26,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700327
328 /**
329 * Android dense depth image format.
330 *
331 * <p>Each pixel is 16 bits, representing a depth ranging measurement from a depth camera or
332 * similar sensor. The 16-bit sample consists of a confidence value and the actual ranging
333 * measurement.</p>
334 *
335 * <p>The confidence value is an estimate of correctness for this sample. It is encoded in the
336 * 3 most significant bits of the sample, with a value of 0 representing 100% confidence, a
337 * value of 1 representing 0% confidence, a value of 2 representing 1/7, a value of 3
338 * representing 2/7, and so on.</p>
339 *
340 * <p>As an example, the following sample extracts the range and confidence from the first pixel
341 * of a DEPTH16-format {@link AImage}, and converts the confidence to a floating-point value
342 * between 0 and 1.f inclusive, with 1.f representing maximum confidence:
343 *
344 * <pre>
345 * uint16_t* data;
346 * int dataLength;
347 * AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength);
348 * uint16_t depthSample = data[0];
349 * uint16_t depthRange = (depthSample & 0x1FFF);
350 * uint16_t depthConfidence = ((depthSample >> 13) & 0x7);
351 * float depthPercentage = depthConfidence == 0 ? 1.f : (depthConfidence - 1) / 7.f;
352 * </pre>
353 * </p>
354 *
355 * <p>This format assumes
356 * <ul>
357 * <li>an even width</li>
358 * <li>an even height</li>
359 * <li>a horizontal stride multiple of 16 pixels</li>
360 * </ul>
361 * </p>
362 *
363 * <pre> y_size = stride * height </pre>
364 *
365 * When produced by a camera, the units for the range are millimeters.
366 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800367 AIMAGE_FORMAT_DEPTH16 = 0x44363159,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700368
369 /**
370 * Android sparse depth point cloud format.
371 *
372 * <p>A variable-length list of 3D points plus a confidence value, with each point represented
373 * by four floats; first the X, Y, Z position coordinates, and then the confidence value.</p>
374 *
375 * <p>The number of points is ((size of the buffer in bytes) / 16).
376 *
377 * <p>The coordinate system and units of the position values depend on the source of the point
378 * cloud data. The confidence value is between 0.f and 1.f, inclusive, with 0 representing 0%
379 * confidence and 1.f representing 100% confidence in the measured position values.</p>
380 *
381 * <p>As an example, the following code extracts the first depth point in a DEPTH_POINT_CLOUD
382 * format {@link AImage}:
383 * <pre>
384 * float* data;
385 * int dataLength;
386 * AImage_getPlaneData(image, 0, (uint8_t**)&data, &dataLength);
387 * float x = data[0];
388 * float y = data[1];
389 * float z = data[2];
390 * float confidence = data[3];
391 * </pre>
392 *
393 */
Yin-Chia Yeh3e49be12016-04-12 16:00:33 -0700394 AIMAGE_FORMAT_DEPTH_POINT_CLOUD = 0x101,
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700395
396 /**
397 * Android private opaque image format.
398 *
399 * <p>This format is not currently supported by {@link AImageReader}.</p>
400 */
401 AIMAGE_FORMAT_PRIVATE = 0x22
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800402};
403
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700404/**
405 * Data type describing an cropped rectangle returned by {@link AImage_getCropRect}.
406 *
407 * <p>Note that the right and bottom coordinates are exclusive, so the width of the rectangle is
408 * (right - left) and the height of the rectangle is (bottom - top).</p>
409 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800410typedef struct AImageCropRect {
411 int32_t left;
412 int32_t top;
413 int32_t right;
414 int32_t bottom;
415} AImageCropRect;
416
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700417/**
418 * Return the image back the the system and delete the AImage object from memory.
419 *
420 * <p>Do NOT use the image pointer after this method returns.
421 * Note that if the parent {@link AImageReader} is closed, all the {@link AImage} objects acquired
422 * from the parent reader will be returned to system. All AImage_* methods except this method will
423 * return {@link AMEDIA_ERROR_INVALID_OBJECT}. Application still needs to call this method on those
424 * {@link AImage} objects to fully delete the {@link AImage} object from memory.</p>
425 *
426 * @param image The {@link AImage} to be deleted.
427 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800428void AImage_delete(AImage* image);
429
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700430/**
431 * Query the width of the input {@link AImage}.
432 *
433 * @param image the {@link AImage} of interest.
434 * @param width the width of the image will be filled here if the method call succeeeds.
435 *
436 * @return <ul>
437 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
438 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or width is NULL.</li>
439 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
440 * image has been deleted.</li></ul>
441 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800442media_status_t AImage_getWidth(const AImage* image, /*out*/int32_t* width);
443
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700444/**
445 * Query the height of the input {@link AImage}.
446 *
447 * @param image the {@link AImage} of interest.
448 * @param height the height of the image will be filled here if the method call succeeeds.
449 *
450 * @return <ul>
451 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
452 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or height is NULL.</li>
453 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
454 * image has been deleted.</li></ul>
455 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800456media_status_t AImage_getHeight(const AImage* image, /*out*/int32_t* height);
457
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700458/**
459 * Query the format of the input {@link AImage}.
460 *
461 * <p>The format value will be one of AIMAGE_FORMAT_* enum value.</p>
462 *
463 * @param image the {@link AImage} of interest.
464 * @param format the format of the image will be filled here if the method call succeeeds.
465 *
466 * @return <ul>
467 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
468 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or format is NULL.</li>
469 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
470 * image has been deleted.</li></ul>
471 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800472media_status_t AImage_getFormat(const AImage* image, /*out*/int32_t* format);
473
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700474/**
475 * Query the cropped rectangle of the input {@link AImage}.
476 *
477 * <p>The crop rectangle specifies the region of valid pixels in the image, using coordinates in the
478 * largest-resolution plane.</p>
479 *
480 * @param image the {@link AImage} of interest.
481 * @param rect the cropped rectangle of the image will be filled here if the method call succeeeds.
482 *
483 * @return <ul>
484 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
485 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or rect is NULL.</li>
486 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
487 * image has been deleted.</li></ul>
488 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800489media_status_t AImage_getCropRect(const AImage* image, /*out*/AImageCropRect* rect);
490
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700491/**
492 * Query the timestamp of the input {@link AImage}.
493 *
494 * <p>
495 * The timestamp is measured in nanoseconds, and is normally monotonically increasing. The
496 * timestamps for the images from different sources may have different timebases therefore may not
497 * be comparable. The specific meaning and timebase of the timestamp depend on the source providing
498 * images. For images generated by camera, the timestamp value will match
499 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in
500 * {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted} and
501 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback.
502 * </p>
503 *
504 * @param image the {@link AImage} of interest.
505 * @param timestampNs the timestamp of the image will be filled here if the method call succeeeds.
506 *
507 * @return <ul>
508 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
509 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or timestampNs is NULL.</li>
510 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
511 * image has been deleted.</li></ul>
512 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800513media_status_t AImage_getTimestamp(const AImage* image, /*out*/int64_t* timestampNs);
514
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700515/**
516 * Query the number of planes of the input {@link AImage}.
517 *
518 * <p>The number of plane of an {@link AImage} is determined by its format, which can be queried by
519 * {@link AImage_getFormat} method.</p>
520 *
521 * @param image the {@link AImage} of interest.
522 * @param numPlanes the number of planes of the image will be filled here if the method call
523 * succeeeds.
524 *
525 * @return <ul>
526 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
527 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or numPlanes is NULL.</li>
528 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
529 * image has been deleted.</li></ul>
530 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800531media_status_t AImage_getNumberOfPlanes(const AImage* image, /*out*/int32_t* numPlanes);
532
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700533/**
534 * Query the pixel stride of the input {@link AImage}.
535 *
536 * <p>This is the distance between two consecutive pixel values in a row of pixels. It may be
537 * larger than the size of a single pixel to account for interleaved image data or padded formats.
538 * Note that pixel stride is undefined for some formats such as {@link AIMAGE_FORMAT_RAW_PRIVATE},
539 * and calling this method on images of these formats will cause {@link AMEDIA_ERROR_UNSUPPORTED}
540 * being returned.
541 * For formats where pixel stride is well defined, the pixel stride is always greater than 0.</p>
542 *
543 * @param image the {@link AImage} of interest.
544 * @param planeIdx the index of the plane. Must be less than the number of planes of input image.
545 * @param pixelStride the pixel stride of the image will be filled here if the method call succeeeds.
546 *
547 * @return <ul>
548 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
549 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or pixelStride is NULL, or planeIdx
550 * is out of the range of [0, numOfPlanes - 1].</li>
551 * <li>{@link AMEDIA_ERROR_UNSUPPORTED} if pixel stride is undefined for the format of input
552 * image.</li>
553 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
554 * image has been deleted.</li></ul>
555 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800556media_status_t AImage_getPlanePixelStride(
557 const AImage* image, int planeIdx, /*out*/int32_t* pixelStride);
558
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700559/**
560 * Query the row stride of the input {@link AImage}.
561 *
562 * <p>This is the distance between the start of two consecutive rows of pixels in the image. Note
563 * that row stried is undefined for some formats such as {@link AIMAGE_FORMAT_RAW_PRIVATE}, and
564 * calling this method on images of these formats will cause {@link AMEDIA_ERROR_UNSUPPORTED}
565 * being returned.
566 * For formats where row stride is well defined, the row stride is always greater than 0.</p>
567 *
568 * @param image the {@link AImage} of interest.
569 * @param planeIdx the index of the plane. Must be less than the number of planes of input image.
570 * @param rowStride the row stride of the image will be filled here if the method call succeeeds.
571 *
572 * @return <ul>
573 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
574 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or rowStride is NULL, or planeIdx
575 * is out of the range of [0, numOfPlanes - 1].</li>
576 * <li>{@link AMEDIA_ERROR_UNSUPPORTED} if row stride is undefined for the format of input
577 * image.</li>
578 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
579 * image has been deleted.</li></ul>
580 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800581media_status_t AImage_getPlaneRowStride(
582 const AImage* image, int planeIdx, /*out*/int32_t* rowStride);
583
Yin-Chia Yeh1d0955c2016-05-16 01:14:13 -0700584/**
585 * Get the data pointer of the input image for direct application access.
586 *
587 * <p>Note that once the {@link AImage} or the parent {@link AImageReader} is deleted, the data
588 * pointer from previous AImage_getPlaneData call becomes invalid. Do NOT use it after the
589 * {@link AImage} or the parent {@link AImageReader} is deleted.</p>
590 *
591 * @param image the {@link AImage} of interest.
592 * @param planeIdx the index of the plane. Must be less than the number of planes of input image.
593 * @param data the data pointer of the image will be filled here if the method call succeeeds.
594 * @param dataLength the valid length of data will be filled here if the method call succeeeds.
595 *
596 * @return <ul>
597 * <li>{@link AMEDIA_OK} if the method call succeeds.</li>
598 * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image, data or dataLength is NULL, or
599 * planeIdx is out of the range of [0, numOfPlanes - 1].</li>
600 * <li>{@link AMEDIA_ERROR_INVALID_OBJECT} if the {@link AImageReader} generated this
601 * image has been deleted.</li></ul>
602 */
Yin-Chia Yehc3603822016-01-18 22:11:19 -0800603media_status_t AImage_getPlaneData(
604 const AImage* image, int planeIdx,
605 /*out*/uint8_t** data, /*out*/int* dataLength);
606
607#ifdef __cplusplus
608} // extern "C"
609#endif
610
611#endif //_NDK_IMAGE_H
Yin-Chia Yeh3e49be12016-04-12 16:00:33 -0700612
613/** @} */