Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 355d9904 authored by Jiwen 'Steve' Cai's avatar Jiwen 'Steve' Cai
Browse files

Extending AImage/AImageReader headers 

This introduces new API that allows AHardwareBuffer access via
AImage/AImageReader.

Bug: 35114769
Test: Build (should have no functional change from headers change), and
existing CTS tests run using cts-tradefed on a Pixel.

Change-Id: I7b6505ca3b9489d86eb564d1ae5707fd3fa25668
parent 9470b9e3

include/ndk/NdkImage.h

+51 −0
Original line number Diff line number Diff line
@@ -40,6 +40,10 @@ 


#include "NdkMediaError.h"



#if __ANDROID_API__ >= 26

#include <android/hardware_buffer.h>

#endif /* __ANDROID_API__ >= 26 */



#ifdef __cplusplus

extern "C" {

#endif
@@ -707,6 +711,53 @@ media_status_t AImage_getPlaneData( 


#endif /* __ANDROID_API__ >= 24 */



#if __ANDROID_API__ >= 26



/*

 * Return the image back the the system and delete the AImage object from memory asynchronously.

 *

 * <p>Similar to {@link AImage_delete}, do NOT use the image pointer after this method returns.

 * However, the caller can still hold on to the {@link AHardwareBuffer} returned from this image and

 * signal the release of the hardware buffer back to the {@link AImageReader}'s queue using

 * releaseFenceFd.</p>

 *

 * @param image The {@link AImage} to be deleted.

 * @param releaseFenceFd A sync fence fd defined in {@link sync.h}, which signals the release of

 *         underlying {@link AHardwareBuffer}.

 *

 * @see sync.h

 */

void AImage_deleteAsync(AImage* image, int releaseFenceFd);



/**

 * Get the hardware buffer handle of the input image intended for GPU and/or hardware access.

 *

 * <p>Note that no reference on the returned {@link AHardwareBuffer} handle is acquired

 * automatically. Once the {@link AImage} or the parent {@link AImageReader} is deleted, the

 * {@link AHardwareBuffer} handle from previous {@link AImage_getHardwareBuffer} becomes

 * invalid.</p>

 *

 * <p>If the caller ever needs to hold on a reference to the {@link AHardwareBuffer} handle after

 * the {@link AImage} or the parent {@link AImageReader} is deleted, it must call {@link

 * AHardwareBuffer_acquire} to acquire an extra reference, and call {@link AHardwareBuffer_release}

 * once it has finished using it in order to properly deallocate the underlying memory managed by

 * {@link AHardwareBuffer}. If the caller has acquired extra reference on an {@link AHardwareBuffer}

 * returned from this function, it must also listen to {@link onBufferFreed} callback to be

 * notified when the buffer is no longer used by {@link AImageReader}.</p>

 *

 * @param image the {@link AImage} of interest.

 * @param outBuffer The memory area pointed to by buffer will contain the acquired AHardwareBuffer

 *         handle.

 * @return <ul>

 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>

 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if image or buffer is NULL</li></ul>

 *

 * @see AImageReader_ImageCallback

 */

media_status_t AImage_getHardwareBuffer(const AImage* image, /*out*/AHardwareBuffer** buffer);



#endif /* __ANDROID_API__ >= 26 */



#ifdef __cplusplus

} // extern "C"

#endif

include/ndk/NdkImageReader.h

+121 −0
Original line number Diff line number Diff line
@@ -300,6 +300,127 @@ media_status_t AImageReader_setImageListener( 


#endif /* __ANDROID_API__ >= 24 */



#if __ANDROID_API__ >= 26



/**

 * AImageReader constructor similar to {@link AImageReader_new} that takes an additional parameter

 * for the consumer usage. All other parameters and the return values are identical to those passed

 * to {@line AImageReader_new}.

 *

 * @param usage0 specifies how the consumer will access the AImage, using combination of the

 *            AHARDWAREBUFFER_USAGE0 flags described in {@link hardware_buffer.h}.

 *            Passing {@link AHARDWAREBUFFER_USAGE0_CPU_READ_OFTEN} is equivalent to calling

 *            {@link AImageReader_new} with the same parameters. Note that consumers that do not

 *            require CPU access to the buffer should omit {@link

 *            AHARDWAREBUFFER_USAGE0_CPU_READ_OFTEN} to improve performance.

 * @param usage1 specifies how the consumer will access the AImage, using combination of the

 *            AHARDWAREBUFFER_USAGE1 flags described in {@link hardware_buffer.h}.

 *

 * @see AImage

 * @see AImageReader_new

 * @see AHardwareBuffer

 */

media_status_t AImageReader_newWithUsage(

        int32_t width, int32_t height, int32_t format, uint64_t usage0,

        uint64_t usage1, int32_t maxImages, /*out*/ AImageReader** reader);



/*

 * Acquire the next {@link AImage} from the image reader's queue asynchronously.

 *

 * <p>AImageReader acquire method similar to {@link AImageReader_acquireNextImage} that takes an

 * additional parameter for the sync fence. All other parameters and the return values are

 * identical to those passed to {@link AImageReader_acquireNextImage}.</p>

 *

 * @param acquireFenceFd A sync fence fd defined in {@link sync.h}, which is used to signal when the

 *         buffer is ready to consume. When synchronization fence is not needed, fence will be set

 *         to -1 and the {@link AImage} returned is ready for use immediately. Otherwise, user shall

 *         use syscalls such as {@code poll()}, {@code epoll()}, {@code select()} to wait for the

 *         fence fd to change status before attempting to access the {@link AImage} returned.

 *

 * @see sync.h

 * @see sync_get_fence_info

 */

media_status_t AImageReader_acquireNextImageAsync(

        AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);



/*

 * Acquire the latest {@link AImage} from the image reader's queue asynchronously, dropping older

 * images.

 *

 * <p>AImageReader acquire method similar to {@link AImageReader_acquireLatestImage} that takes an

 * additional parameter for the sync fence. All other parameters and the return values are

 * identical to those passed to {@link AImageReader_acquireLatestImage}.</p>

 *

 * @param acquireFenceFd A sync fence fd defined in {@link sync.h}, which is used to signal when the

 *         buffer is ready to consume. When synchronization fence is not needed, fence will be set

 *         to -1 and the {@link AImage} returned is ready for use immediately. Otherwise, user shall

 *         use syscalls such as {@code poll()}, {@code epoll()}, {@code select()} to wait for the

 *         fence fd to change status before attempting to access the {@link AImage} returned.

 *

 * @see sync.h

 * @see sync_get_fence_info

 */

media_status_t AImageReader_acquireLatestImageAsync(

        AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);

/**

 * The definition of {@link AImageReader} buffer removed callback.

 *

 * @param context The optional application context provided by user in

 *                {@link AImageReader_setBufferRemovedListener}.

 * @param reader The {@link AImageReader} of interest.

 * @param buffer The {@link AHardwareBuffer} that is being removed from this image reader.

 */

typedef void (*AImageReader_BufferRemovedCallback)(void* context,

        AImageReader* reader,

        AHardwareBuffer* buffer);



typedef struct AImageReader_BufferRemovedListener {

    /// optional application context.

    void*                      context;



    /**

     * This callback is called when an old {@link AHardwareBuffer} is about to be removed from the

     * image reader.

     *

     * <p>Note that registering this callback is optional unless the user holds on extra reference

     * to {@link AHardwareBuffer} returned from {@link AImage_getHardwareBuffer} by calling {@link

     * AHardwareBuffer_acquire} or creating external graphic objects, such as EglImage, from it.</p>

     *

     * <p>If the callback is registered, the {@link AImageReader} will hold on the last of its

     * references to the {@link AHardwareBuffer} until this callback returns. User can use the

     * callback to get notified that it becomes the last owner of the buffer. It is up to the user

     * to decide to either 1) immediately release all of its references to the buffer; or 2) keep

     * using the buffer and release it in future. Note that, if option 2 if used, user of this API

     * is responsible to deallocate the buffer properly by calling {@link AHardwareBuffer_release}.

     * </p>

     *

     * @see AHardwareBuffer_release

     * @see AImage_getHardwareBuffer

     */

    AImageReader_BufferRemovedCallback onBufferRemoved;

} AImageReader_BufferRemovedListener;



/**

 * Set the onBufferRemoved listener of this image reader.

 *

 * <p>Note that calling this method will replace previously registered listeners.</p>

 *

 * @param reader The image reader of interest.

 * @param listener the {@link AImageReader_BufferRemovedListener} to be registered. Set this to

 * NULL if application no longer needs to listen to buffer removed events.

 *

 * @return <ul>

 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>

 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL.</li></ul>

 *

 * @see AImage_getHardwareBuffer

 */

media_status_t AImageReader_setBufferRemovedListener(

        AImageReader* reader, AImageReader_BufferRemovedListener* listener);



#endif /* __ANDROID_API__ >= 26 */





#ifdef __cplusplus

} // extern "C"

#endif