1/*
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
17/**
18 * @addtogroup Media Camera
19 * @{
20 */
21
22/**
23 * @file NdkImage.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_IMAGE_H
37#define _NDK_IMAGE_H
38
39#include "NdkMediaError.h"
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 * AImage is an opaque type that provides access to image generated by {@link AImageReader}.
47 */
48typedef struct AImage AImage;
49
50// Formats not listed here will not be supported by AImageReader
51enum 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     */
84    AIMAGE_FORMAT_YUV_420_888       = 0x23,
85
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     */
91    AIMAGE_FORMAT_JPEG              = 0x100,
92
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     */
102    AIMAGE_FORMAT_RAW16             = 0x20,
103
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     */
112    AIMAGE_FORMAT_RAW_PRIVATE       = 0x24,
113
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     */
230    AIMAGE_FORMAT_RAW10             = 0x25,
231
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     */
326    AIMAGE_FORMAT_RAW12             = 0x26,
327
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     */
367    AIMAGE_FORMAT_DEPTH16           = 0x44363159,
368
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     */
394    AIMAGE_FORMAT_DEPTH_POINT_CLOUD = 0x101,
395
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
402};
403
404/**
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 */
410typedef struct AImageCropRect {
411    int32_t left;
412    int32_t top;
413    int32_t right;
414    int32_t bottom;
415} AImageCropRect;
416
417/**
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 */
428void AImage_delete(AImage* image);
429
430/**
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 */
442media_status_t AImage_getWidth(const AImage* image, /*out*/int32_t* width);
443
444/**
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 */
456media_status_t AImage_getHeight(const AImage* image, /*out*/int32_t* height);
457
458/**
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 */
472media_status_t AImage_getFormat(const AImage* image, /*out*/int32_t* format);
473
474/**
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 */
489media_status_t AImage_getCropRect(const AImage* image, /*out*/AImageCropRect* rect);
490
491/**
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 */
513media_status_t AImage_getTimestamp(const AImage* image, /*out*/int64_t* timestampNs);
514
515/**
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 */
531media_status_t AImage_getNumberOfPlanes(const AImage* image, /*out*/int32_t* numPlanes);
532
533/**
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 */
556media_status_t AImage_getPlanePixelStride(
557        const AImage* image, int planeIdx, /*out*/int32_t* pixelStride);
558
559/**
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 */
581media_status_t AImage_getPlaneRowStride(
582        const AImage* image, int planeIdx, /*out*/int32_t* rowStride);
583
584/**
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 */
603media_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
612
613/** @} */
614