1c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh/* 2c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Copyright (C) 2016 The Android Open Source Project 3c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * 4c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Licensed under the Apache License, Version 2.0 (the "License"); 5c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * you may not use this file except in compliance with the License. 6c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * You may obtain a copy of the License at 7c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * 8c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * http://www.apache.org/licenses/LICENSE-2.0 9c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * 10c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Unless required by applicable law or agreed to in writing, software 11c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * distributed under the License is distributed on an "AS IS" BASIS, 12c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * See the License for the specific language governing permissions and 14c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * limitations under the License. 15c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh */ 16c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 173e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh/** 183e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh * @addtogroup Media Camera 193e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh * @{ 203e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh */ 213e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh 223e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh/** 233e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh * @file NdkImageReader.h 243e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh */ 253e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh 26c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh/* 27c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * This file defines an NDK API. 28c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not remove methods. 29c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not change method signatures. 30c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not change the value of constants. 31c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not change the size of any of the classes defined in here. 32c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not reference types that are not part of the NDK. 33c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh * Do not #include files that aren't part of the NDK. 34c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh */ 35c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 36c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#ifndef _NDK_IMAGE_READER_H 37c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#define _NDK_IMAGE_READER_H 38c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 39c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#include <android/native_window.h> 40c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#include "NdkMediaError.h" 41c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#include "NdkImage.h" 42c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 43c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#ifdef __cplusplus 44c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehextern "C" { 45c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#endif 46c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 471d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 481d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * AImage is an opaque type that allows direct application access to image data rendered into a 491d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link ANativeWindow}. 501d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 51c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehtypedef struct AImageReader AImageReader; 52c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 531d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 541d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Create a new reader for images of the desired size and format. 551d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 561d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 571d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * The maxImages parameter determines the maximum number of {@link AImage} objects that can be 581d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * acquired from the {@link AImageReader} simultaneously. Requesting more buffers will use up 591d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * more memory, so it is important to use only the minimum number necessary for the use case. 601d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 611d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 621d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * The valid sizes and formats depend on the source of the image data. 631d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 641d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 651d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param width The default width in pixels of the Images that this reader will produce. 661d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param height The default height in pixels of the Images that this reader will produce. 671d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param format The format of the Image that this reader will produce. This must be one of the 681d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * AIMAGE_FORMAT_* enum value defined in {@link AIMAGE_FORMATS}. Note that not all 691d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * formats are supported, like {@link AIMAGE_FORMAT_PRIVATE}. 701d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param maxImages The maximum number of images the user will want to access simultaneously. This 711d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * should be as small as possible to limit memory use. Once maxImages Images are obtained 721d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * by the user, one of them has to be released before a new {@link AImage} will become 731d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * available for access through {@link AImageReader_acquireLatestImage} or 741d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage}. Must be greater than 0. 751d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The created image reader will be filled here if the method call succeeeds. 761d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 771d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 781d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 791d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL, or one or more of width, 801d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * height, format, maxImages arguments is not supported.</li> 811d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 821d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 831d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @see AImage 841d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 85c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_new( 86c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh int32_t width, int32_t height, int32_t format, int32_t maxImages, 87c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh /*out*/AImageReader** reader); 88c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 891d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 901d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Delete an {@link AImageReader} and return all images generated by this reader to system. 911d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 921d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>This method will return all {@link AImage} objects acquired by this reader (via 931d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}) to system, 941d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * making any of data pointers obtained from {@link AImage_getPlaneData} invalid. Do NOT access 951d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * the reader object or any of those data pointers after this method returns.</p> 961d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 971d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader to be deleted. 981d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 99c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehvoid AImageReader_delete(AImageReader* reader); 100c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 1011d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1021d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Get a {@link ANativeWindow} that can be used to produce {@link AImage} for this image reader. 1031d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1041d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1051d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param window The output {@link ANativeWindow} will be filled here if the method call succeeds. 1061d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * The {@link ANativeWindow} is managed by this image reader. Do NOT call 1071d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link ANativeWindow_release} on it. Instead, use {@link AImageReader_delete}. 1081d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1091d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1101d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1111d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or window is NULL.</li></ul> 1121d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 1131d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yehmedia_status_t AImageReader_getWindow(AImageReader* reader, /*out*/ANativeWindow** window); 114c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 1151d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1161d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Query the default width of the {@link AImage} generated by this reader, in pixels. 1171d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1181d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>The width may be overridden by the producer sending buffers to this reader's 1191d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link ANativeWindow}. If so, the actual width of the images can be found using 1201d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_getWidth}.</p> 1211d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1221d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1231d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param width the default width of the reader will be filled here if the method call succeeeds. 1241d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1251d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1261d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1271d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or width is NULL.</li></ul> 1281d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 129c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_getWidth(const AImageReader* reader, /*out*/int32_t* width); 1301d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 1311d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1321d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Query the default height of the {@link AImage} generated by this reader, in pixels. 1331d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1341d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>The height may be overridden by the producer sending buffers to this reader's 1351d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link ANativeWindow}. If so, the actual height of the images can be found using 1361d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_getHeight}.</p> 1371d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1381d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1391d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param height the default height of the reader will be filled here if the method call succeeeds. 1401d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1411d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1421d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1431d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or height is NULL.</li></ul> 1441d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 145c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_getHeight(const AImageReader* reader, /*out*/int32_t* height); 1461d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 1471d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1481d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Query the format of the {@link AImage} generated by this reader. 1491d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1501d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1511d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param format the fromat of the reader will be filled here if the method call succeeeds. The 1521d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * value will be one of the AIMAGE_FORMAT_* enum value defiend in {@link NdkImage.h}. 1531d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1541d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1551d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1561d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or format is NULL.</li></ul> 1571d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 158c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_getFormat(const AImageReader* reader, /*out*/int32_t* format); 1591d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 1601d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1611d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Query the maximum number of concurrently acquired {@link AImage}s of this reader. 1621d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1631d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1641d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param maxImages the maximum number of concurrently acquired images of the reader will be filled 1651d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * here if the method call succeeeds. 1661d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1671d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1681d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1691d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or maxImages is NULL.</li></ul> 1701d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 171c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_getMaxImages(const AImageReader* reader, /*out*/int32_t* maxImages); 172c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 1731d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 1741d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Acquire the next {@link AImage} from the image reader's queue. 1751d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1761d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>Warning: Consider using {@link AImageReader_acquireLatestImage} instead, as it will 1771d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * automatically release older images, and allow slower-running processing routines to catch 1781d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * up to the newest frame. Usage of {@link AImageReader_acquireNextImage} is recommended for 1791d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * batch/background processing. Incorrectly using this method can cause images to appear 1801d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * with an ever-increasing delay, followed by a complete stall where no new images seem to appear. 1811d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 1821d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1831d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 1841d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with 1851d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular 1861d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage} 1871d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * calls greater than {@link AImageReader_getMaxImages maxImages} without calling 1881d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time, 1891d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with 1901d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_delete}. 1911d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 1921d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1931d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 1941d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param image the acquired {@link AImage} will be filled here if the method call succeeeds. 1951d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 1961d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 1971d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 1981d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li> 1991d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired 2001d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * images has reached the limit.</li> 2011d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently 2021d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * available in the reader queue.</li> 2031d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 2041d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2051d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @see AImageReader_acquireLatestImage 2061d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 207c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_acquireNextImage(AImageReader* reader, /*out*/AImage** image); 208c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 2091d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 2101d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 2111d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Acquire the latest {@link AImage} from the image reader's queue, dropping older images. 2121d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2131d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 2141d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * This operation will acquire all the images possible from the image reader, but 2151d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_delete} all images that aren't the latest. This function is recommended to use over 2161d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage} for most use-cases, as it's more suited for real-time 2171d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * processing. 2181d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 2191d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 2201d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Note that {@link AImageReader_getMaxImages maxImages} should be at least 2 for 2211d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireLatestImage} to be any different than 2221d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage} - discarding all-but-the-newest {@link AImage} requires 2231d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * temporarily acquiring two {@link AImage}s at once. Or more generally, calling 2241d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireLatestImage} with less than two images of margin, that is 2251d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * (maxImages - currentAcquiredImages < 2) will not discard as expected. 2261d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 2271d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p> 2281d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with 2291d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular 2301d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage} 2311d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * calls greater than {@link AImageReader_getMaxImages maxImages} without calling 2321d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time, 2331d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with 2341d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImage_delete}. 2351d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * </p> 2361d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2371d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 2381d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param image the acquired {@link AImage} will be filled here if the method call succeeeds. 2391d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2401d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 2411d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 2421d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li> 2431d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired 2441d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * images has reached the limit.</li> 2451d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently 2461d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * available in the reader queue.</li> 2471d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 2481d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2491d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @see AImageReader_acquireNextImage 2501d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 251c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_acquireLatestImage(AImageReader* reader, /*out*/AImage** image); 252c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 2531d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 2541d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 2551d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * The definition of {@link AImageReader} new image available callback. 2561d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2571d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param context The optional application context provided by user in 2581d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_setImageListener}. 2591d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param session The camera capture session whose state is changing. 2601d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 261c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehtypedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader); 262c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 263c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehtypedef struct AImageReader_ImageListener { 2641d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh /// optional application context. 2651d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh void* context; 2661d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh 2671d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh /** 2681d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * This callback is called when there is a new image available for in the image reader's queue. 2691d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2701d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>The callback happens on one dedicated thread per {@link AImageReader} instance. It is okay 2711d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * to use AImageReader_* and AImage_* methods within the callback. Note that it is possible that 2721d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * calling {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage} 2731d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * returns {@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} within this callback. For example, when 2741d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * there are multiple images and callbacks queued, if application called 2751d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * {@link AImageReader_acquireLatestImage}, some images will be returned to system before their 2761d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * corresponding callback is executed.</p> 2771d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 278c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh AImageReader_ImageCallback onImageAvailable; 279c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh} AImageReader_ImageListener; 280c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 2811d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh/** 2821d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * Set the onImageAvailable listener of this image reader. 2831d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2841d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <p>Note that calling this method will replace previously registered listeners.</p> 2851d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2861d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param reader The image reader of interest. 2871d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @param listener the {@link AImageReader_ImageListener} to be registered. Set this to NULL if 2881d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * application no longer needs to listen to new images. 2891d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * 2901d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * @return <ul> 2911d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_OK} if the method call succeeds.</li> 2921d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh * <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL.</li></ul> 2931d0955cb5257a59f0ae435fefe26c05af4f4fbb6Yin-Chia Yeh */ 294c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yehmedia_status_t AImageReader_setImageListener( 295c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh AImageReader* reader, AImageReader_ImageListener* listener); 296c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 297c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#ifdef __cplusplus 298c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh} // extern "C" 299c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#endif 300c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh 301c360382bf257d815b2a411152485d3c3b37a9f46Yin-Chia Yeh#endif //_NDK_IMAGE_READER_H 3023e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh 3033e49be17d8c8c53f50bb0d39affbbc36f6a12488Yin-Chia Yeh/** @} */ 304