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

Commit 1d0955cb authored by Yin-Chia Yeh's avatar Yin-Chia Yeh
Browse files

CameraNDK: fill in more NDK API documents 

This change adds document for ACaptureRequest, ACameraMetadata,
AImage and AImageReader.

Bug: 27102995
Change-Id: I79d88f73258c01ebeabcd5b4e3b90996759cb021
parent 77404e1a

camera/ndk/impl/ACameraMetadata.h

+9 −3
Original line number Diff line number Diff line
@@ -79,9 +79,15 @@ struct ACameraMetadata : public RefBase { 


        Mutex::Autolock _l(mLock);



        status_t ret = OK;

        if (count == 0 && data == nullptr) {

            ret = mData.erase(tag);

        } else {

            // Here we have to use reinterpret_cast because the NDK data type is

            // exact copy of internal data type but they do not inherit from each other

        status_t ret = mData.update(tag, reinterpret_cast<const INTERNAL_T*>(data), count);

            ret = mData.update(tag, reinterpret_cast<const INTERNAL_T*>(data), count);

        }



        if (ret == OK) {

            mTags.clear();

            return ACAMERA_OK;

include/camera/ndk/NdkCameraCaptureSession.h

+5 −2
Original line number Diff line number Diff line
@@ -177,7 +177,8 @@ typedef void (*ACameraCaptureSession_captureCallback_start)( 
 *                capture request sent by application, so the address is different to what

 *                application sent but the content will match. This request will be freed by

 *                framework immediately after this callback returns.

 * @param result The capture result metadata reported by camera device

 * @param result The capture result metadata reported by camera device. The memory is managed by

 *                camera framework. Do not access this pointer after this callback returns.

 */

typedef void (*ACameraCaptureSession_captureCallback_result)(

        void* context, ACameraCaptureSession* session,
@@ -193,7 +194,9 @@ typedef void (*ACameraCaptureSession_captureCallback_result)( 
 *                capture request sent by application, so the address is different to what

 *                application sent but the content will match. This request will be freed by

 *                framework immediately after this callback returns.

 * @param failure The {@link ACameraCaptureFailure} desribes the capture failure.

 * @param failure The {@link ACameraCaptureFailure} desribes the capture failure. The memory is

 *                managed by camera framework. Do not access this pointer after this callback

 *                returns.

 */

typedef void (*ACameraCaptureSession_captureCallback_failed)(

        void* context, ACameraCaptureSession* session,

include/camera/ndk/NdkCameraMetadata.h

+125 −22
Original line number Diff line number Diff line
@@ -43,35 +43,78 @@ 
extern "C" {

#endif



/**

 * ACameraMetadata is opaque type that provides access to read-only camera metadata like camera

 * characteristics (via {@link ACameraManager_getCameraCharacteristics}) or capture results (via

 * {@link ACameraCaptureSession_captureCallback_result}).

 */

typedef struct ACameraMetadata ACameraMetadata;



// Keep in sync with system/media/include/system/camera_metadata.h

/**

 * Possible data types of a metadata entry.

 *

 * Keep in sync with system/media/include/system/camera_metadata.h

 */

enum {

    // Unsigned 8-bit integer (uint8_t)

    /// Unsigned 8-bit integer (uint8_t)

    ACAMERA_TYPE_BYTE = 0,

    // Signed 32-bit integer (int32_t)

    /// Signed 32-bit integer (int32_t)

    ACAMERA_TYPE_INT32 = 1,

    // 32-bit float (float)

    /// 32-bit float (float)

    ACAMERA_TYPE_FLOAT = 2,

    // Signed 64-bit integer (int64_t)

    /// Signed 64-bit integer (int64_t)

    ACAMERA_TYPE_INT64 = 3,

    // 64-bit float (double)

    /// 64-bit float (double)

    ACAMERA_TYPE_DOUBLE = 4,

    // A 64-bit fraction (ACameraMetadata_rational)

    /// A 64-bit fraction (ACameraMetadata_rational)

    ACAMERA_TYPE_RATIONAL = 5,

    // Number of type fields

    /// Number of type fields

    ACAMERA_NUM_TYPES

};



/**

 * Definition of rational data type in {@link ACameraMetadata}.

 */

typedef struct ACameraMetadata_rational {

    int32_t numerator;

    int32_t denominator;

} ACameraMetadata_rational;



/**

 * A single camera metadata entry.

 *

 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the

 * array.</p>

 */

typedef struct ACameraMetadata_entry {

    /**

     * The tag identifying the entry.

     *

     * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the

     * entry should be interpreted and which parts of the API provide it.

     * See {@link NdkCameraMetadataTags.h} for more details. </p>

     */

    uint32_t tag;



    /**

     * The data type of this metadata entry.

     *

     * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the

     * same type.</p>

     */

    uint8_t  type;



    /**

     * Count of elements (NOT count of bytes) in this metadata entry.

     */

    uint32_t count;



    /**

     * Pointer to the data held in this metadata entry.

     *

     * <p>The type field above defines which union member pointer is valid. The count field above

     * defines the length of the data in number of elements.</p>

     */

    union {

        uint8_t *u8;

        int32_t *i32;
@@ -82,10 +125,41 @@ typedef struct ACameraMetadata_entry { 
    } data;

} ACameraMetadata_entry;



/**

 * A single read-only camera metadata entry.

 *

 * <p>Each entry is an array of values, though many metadata fields may only have 1 entry in the

 * array.</p>

 */

typedef struct ACameraMetadata_const_entry {

    /**

     * The tag identifying the entry.

     *

     * <p> It is one of the values defined in {@link NdkCameraMetadataTags.h}, and defines how the

     * entry should be interpreted and which parts of the API provide it.

     * See {@link NdkCameraMetadataTags.h} for more details. </p>

     */

    uint32_t tag;



    /**

     * The data type of this metadata entry.

     *

     * <p>Must be one of ACAMERA_TYPE_* enum values defined above. A particular tag always has the

     * same type.</p>

     */

    uint8_t  type;



    /**

     * Count of elements (NOT count of bytes) in this metadata entry.

     */

    uint32_t count;



    /**

     * Pointer to the data held in this metadata entry.

     *

     * <p>The type field above defines which union member pointer is valid. The count field above

     * defines the length of the data in number of elements.</p>

     */

    union {

        const uint8_t *u8;

        const int32_t *i32;
@@ -96,32 +170,61 @@ typedef struct ACameraMetadata_const_entry { 
    } data;

} ACameraMetadata_const_entry;



/*

 * Get a metadata entry

/**

 * Get a metadata entry from an input {@link ACameraMetadata}.

 *

 * <p>The memory of the data field in the returned entry is managed by camera framework. Do not

 * attempt to free it.</p>

 *

 * @param metadata the {@link ACameraMetadata} of interest.

 * @param tag the tag value of the camera metadata entry to be get.

 * @param entry the output {@link ACameraMetadata_const_entry} will be filled here if the method

 *        call succeeeds.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata or entry is NULL.</li>

 *         <li>{@link ACAMERA_ERROR_METADATA_NOT_FOUND} if input metadata does not contain an entry

 *             of input tag value.</li></ul>

 */

camera_status_t ACameraMetadata_getConstEntry(

        const ACameraMetadata*, uint32_t tag, ACameraMetadata_const_entry* entry);

        const ACameraMetadata* metadata, uint32_t tag, /*out*/ACameraMetadata_const_entry* entry);



/*

 * List all the entry tags in this metadata.

 * The memory of tags is managed by ACameraMetadata itself and must NOT be free/delete

 * by application. Do NOT access tags after calling ACameraMetadata_free

/**

 * List all the entry tags in input {@link ACameraMetadata}.

 *

 * @param metadata the {@link ACameraMetadata} of interest.

 * @param numEntries number of metadata entries in input {@link ACameraMetadata}

 * @param tags the tag values of the metadata entries. Length of tags is returned in numEntries

 *             argument. The memory is managed by ACameraMetadata itself and must NOT be free/delete

 *             by application. Do NOT access tags after calling ACameraMetadata_free.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata, numEntries or tags is NULL.</li>

 *         <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>

 */

camera_status_t ACameraMetadata_getAllTags(

        const ACameraMetadata*, /*out*/int32_t* numTags, /*out*/const uint32_t** tags);

        const ACameraMetadata* metadata, /*out*/int32_t* numEntries, /*out*/const uint32_t** tags);



/**

 * Copy a metadata. Duplicates a metadata structure.

 * The destination ACameraMetadata must be freed by the application with ACameraMetadata_free

 * after application is done using it.

 * Returns NULL when src cannot be copied

 * Create a copy of input {@link ACameraMetadata}.

 *

 * <p>The returned ACameraMetadata must be freed by the application by {@link ACameraMetadata_free}

 * after application is done using it.</p>

 *

 * @param src the input {@link ACameraMetadata} to be copied.

 *

 * @return a valid ACameraMetadata pointer or NULL if the input metadata cannot be copied.

 */

ACameraMetadata* ACameraMetadata_copy(const ACameraMetadata* src);



/**

 * Frees a metadata structure.

 * Free a {@link ACameraMetadata} structure.

 *

 * @param metadata the {@link ACameraMetadata} to be freed.

 */

void ACameraMetadata_free(ACameraMetadata*);

void ACameraMetadata_free(ACameraMetadata* metadata);



#ifdef __cplusplus

} // extern "C"

include/camera/ndk/NdkCaptureRequest.h

+230 −29
Original line number Diff line number Diff line
@@ -49,54 +49,255 @@ typedef struct ACameraOutputTargets ACameraOutputTargets; 
// Container for a single output target

typedef struct ACameraOutputTarget ACameraOutputTarget;



/**

 * ACaptureRequest is an opaque type that contains settings and output targets needed to capture

 * a single image from camera device.

 *

 * <p>ACaptureRequest contains the configuration for the capture hardware (sensor, lens, flash),

 * the processing pipeline, the control algorithms, and the output buffers. Also

 * contains the list of target {@link ANativeWindow}s to send image data to for this

 * capture.</p>

 *

 * <p>ACaptureRequest is created by {@link ACameraDevice_createCaptureRequest}.

 *

 * <p>ACaptureRequest is given to {@link ACameraCaptureSession_capture} or

 * {@link ACameraCaptureSession_setRepeatingRequest} to capture images from a camera.</p>

 *

 * <p>Each request can specify a different subset of target {@link ANativeWindow}s for the

 * camera to send the captured data to. All the {@link ANativeWindow}s used in a request must

 * be part of the {@link ANativeWindow} list given to the last call to

 * {@link ACameraDevice_createCaptureSession}, when the request is submitted to the

 * session.</p>

 *

 * <p>For example, a request meant for repeating preview might only include the

 * {@link ANativeWindow} for the preview SurfaceView or SurfaceTexture, while a

 * high-resolution still capture would also include a {@link ANativeWindow} from a

 * {@link AImageReader} configured for high-resolution JPEG images.</p>

 *

 * @see ACameraDevice_createCaptureRequest

 * @see ACameraCaptureSession_capture

 * @see ACameraCaptureSession_setRepeatingRequest

 */

typedef struct ACaptureRequest ACaptureRequest;



camera_status_t ACameraOutputTarget_create(ANativeWindow* window, ACameraOutputTarget** out);

void ACameraOutputTarget_free(ACameraOutputTarget*);

/**

 * Create a ACameraOutputTarget object.

 *

 * <p>The ACameraOutputTarget is used in {@link ACaptureRequest_addTarget} method to add an output

 * {@link ANativeWindow} to ACaptureRequest. Use {@link ACameraOutputTarget_free} to free the object

 * and its memory after application no longer needs the {@link ACameraOutputTarget}.</p>

 *

 * @param window the {@link ANativeWindow} to be associated with the {@link ACameraOutputTarget}

 * @param output the output {@link ACameraOutputTarget} will be stored here if the

 *                  method call succeeds.

 *

 * @return <ul>

 *         <li>{@link ACAMERA_OK} if the method call succeeds. The created ACameraOutputTarget will

 *                                be filled in the output argument.</li>

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if window or output is NULL.</li></ul>

 *

 * @see ACaptureRequest_addTarget

 */

camera_status_t ACameraOutputTarget_create(ANativeWindow* window, ACameraOutputTarget** output);



camera_status_t ACaptureRequest_addTarget(ACaptureRequest*, const ACameraOutputTarget*);

camera_status_t ACaptureRequest_removeTarget(ACaptureRequest*, const ACameraOutputTarget*);

//TODO: do we need API to query added targets?

/**

 * Free a ACameraOutputTarget object.

 *

 * @param output the {@link ACameraOutputTarget} to be freed.

 *

 * @see ACameraOutputTarget_create

 */

void ACameraOutputTarget_free(ACameraOutputTarget* output);



/*

 * Get a metadata entry

/**

 * Add an {@link ACameraOutputTarget} object to {@link ACaptureRequest}.

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param output the output {@link ACameraOutputTarget} to be added to capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request or output is NULL.</li></ul>

 */

camera_status_t ACaptureRequest_addTarget(ACaptureRequest* request,

        const ACameraOutputTarget* output);



/**

 * Remove an {@link ACameraOutputTarget} object from {@link ACaptureRequest}.

 *

 * <p>This method has no effect if the ACameraOutputTarget does not exist in ACaptureRequest.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param output the output {@link ACameraOutputTarget} to be removed from capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request or output is NULL.</li></ul>

 */

camera_status_t ACaptureRequest_removeTarget(ACaptureRequest* request,

        const ACameraOutputTarget* output);



/**

 * Get a metadata entry from input {@link ACaptureRequest}.

 *

 * <p>The memory of the data field in returned entry is managed by camera framework. Do not

 * attempt to free it.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be get.

 * @param entry the output {@link ACameraMetadata_const_entry} will be filled here if the method

 *        call succeeeds.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if metadata or entry is NULL.</li>

 *         <li>{@link ACAMERA_ERROR_METADATA_NOT_FOUND} if the capture request does not contain an

 *             entry of input tag value.</li></ul>

 */

camera_status_t ACaptureRequest_getConstEntry(

        const ACaptureRequest*, uint32_t tag, ACameraMetadata_const_entry* entry);

        const ACaptureRequest* request, uint32_t tag, ACameraMetadata_const_entry* entry);



/*

 * List all the entry tags in this capture request.

 * The memory of tags is managed by ACaptureRequest itself and must NOT be free/delete

 * by application. Calling ACaptureRequest_setEntry_* API will invalidate previous

 * List all the entry tags in input {@link ACaptureRequest}.

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param numEntries number of metadata entries in input {@link ACaptureRequest}

 * @param tags the tag values of the metadata entries. Length of tags is returned in numEntries

 *             argument. The memory is managed by ACaptureRequest itself and must NOT be free/delete

 *             by application. Calling ACaptureRequest_setEntry_* methods will invalidate previous

 *             output of ACaptureRequest_getAllTags. Do not access tags after calling

 *             ACaptureRequest_setEntry_*. To get new list of tags after updating capture request,

 * application must call ACaptureRequest_getAllTags again.

 * Do NOT access tags after calling ACaptureRequest_free.

 *             application must call ACaptureRequest_getAllTags again. Do NOT access tags after

 *             calling ACaptureRequest_free.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request, numEntries or tags is NULL.</li>

 *         <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>

 */

camera_status_t ACaptureRequest_getAllTags(

        const ACaptureRequest*, /*out*/int32_t* numTags, /*out*/const uint32_t** tags);

        const ACaptureRequest* request, /*out*/int32_t* numTags, /*out*/const uint32_t** tags);



/*

 * Set an entry of corresponding type.

 * The entry tag's type must match corresponding set API or an

 * ACAMERA_ERROR_INVALID_PARAMETER error will occur.

 * Also, the input ACameraMetadata* must belong to a capture request or an

 * ACAMERA_ERROR_INVALID_PARAMETER error will occur.

/**

 * Set/change a camera capture control entry with unsigned 8 bits data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not unsigned 8 bits, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_u8(

        ACaptureRequest*, uint32_t tag, uint32_t count, const uint8_t* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count, const uint8_t* data);



/**

 * Set/change a camera capture control entry with signed 32 bits data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not signed 32 bits, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_i32(

        ACaptureRequest*, uint32_t tag, uint32_t count, const int32_t* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count, const int32_t* data);



/**

 * Set/change a camera capture control entry with float data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not float, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_float(

        ACaptureRequest*, uint32_t tag, uint32_t count, const float* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count, const float* data);



/**

 * Set/change a camera capture control entry with signed 64 bits data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not signed 64 bits, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_i64(

        ACaptureRequest*, uint32_t tag, uint32_t count, const int64_t* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count, const int64_t* data);



/**

 * Set/change a camera capture control entry with double data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not double, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_double(

        ACaptureRequest*, uint32_t tag, uint32_t count, const double* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count, const double* data);



/**

 * Set/change a camera capture control entry with rational data type.

 *

 * <p>Set count to 0 and data to NULL to remove a tag from the capture request.</p>

 *

 * @param request the {@link ACaptureRequest} of interest.

 * @param tag the tag value of the camera metadata entry to be set.

 * @param count number of elements to be set in data argument

 * @param data the entries to be set/change in the capture request.

 *

 * @return <ul>

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

 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if request is NULL, count is larger than

 *             zero while data is NULL, the data type of the tag is not rational, or

 *             the tag is not controllable by application.</li></ul>

 */

camera_status_t ACaptureRequest_setEntry_rational(

        ACaptureRequest*, uint32_t tag, uint32_t count, const ACameraMetadata_rational* data);

        ACaptureRequest* request, uint32_t tag, uint32_t count,

        const ACameraMetadata_rational* data);



// free the capture request created by ACameraDevice_createCaptureRequest

/**

 * Free a {@link ACaptureRequest} structure.

 *

 * @param request the {@link ACaptureRequest} to be freed.

 */

void ACaptureRequest_free(ACaptureRequest* request);



#ifdef __cplusplus

include/ndk/NdkImage.h

+518 −16

File changed.

Preview size limit exceeded, changes collapsed.