include/hardware/camera2.h

/*
 * Copyright (C) 2012 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef ANDROID_INCLUDE_CAMERA2_H
#define ANDROID_INCLUDE_CAMERA2_H

#include "camera_common.h"

/**
 * Camera device HAL 2.0 [ CAMERA_DEVICE_API_VERSION_2_0 ]
 *
 * EXPERIMENTAL.
 *
 * Supports both the android.hardware.ProCamera and
 * android.hardware.Camera APIs.
 *
 * Camera devices that support this version of the HAL must return
 * CAMERA_DEVICE_API_VERSION_2_0 in camera_device_t.common.version and in
 * camera_info_t.device_version (from camera_module_t.get_camera_info).
 *
 * Camera modules that may contain version 2.0 devices must implement at least
 * version 2.0 of the camera module interface (as defined by
 * camera_module_t.common.module_api_version).
 *
 * See camera_common.h for more details.
 *
 */

__BEGIN_DECLS

struct camera2_device;

/**
 * Output image stream queue management
 */

typedef struct camera2_stream_ops {
    int (*dequeue_buffer)(struct camera2_stream_ops* w,
                          buffer_handle_t** buffer, int *stride);
    int (*enqueue_buffer)(struct camera2_stream_ops* w,
                buffer_handle_t* buffer);
    int (*cancel_buffer)(struct camera2_stream_ops* w,
                buffer_handle_t* buffer);
    int (*set_buffer_count)(struct camera2_stream_ops* w, int count);
    int (*set_buffers_geometry)(struct camera2_stream_ops* pw,
                int w, int h, int format);
    int (*set_crop)(struct camera2_stream_ops *w,
                int left, int top, int right, int bottom);
    // Timestamps are measured in nanoseconds, and must be comparable
    // and monotonically increasing between two frames in the same
    // preview stream. They do not need to be comparable between
    // consecutive or parallel preview streams, cameras, or app runs.
    // The timestamp must be the time at the start of image exposure.
    int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp);
    int (*set_usage)(struct camera2_stream_ops* w, int usage);
    int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w,
                int *count);
    int (*lock_buffer)(struct camera2_stream_ops* w,
                buffer_handle_t* buffer);
} camera2_stream_ops_t;

/**
 * Metadata queue management, used for requests sent to HAL module, and for
 * frames produced by the HAL.
 *
 * Queue protocol:
 *
 * The source holds the queue and its contents. At start, the queue is empty.
 *
 * 1. When the first metadata buffer is placed into the queue, the source must
 *    signal the destination by calling notify_queue_not_empty().
 *
 * 2. After receiving notify_queue_not_empty, the destination must call
 *    dequeue() once it's ready to handle the next buffer.
 *
 * 3. Once the destination has processed a buffer, it should try to dequeue
 *    another buffer. If there are no more buffers available, dequeue() will
 *    return NULL. In this case, when a buffer becomes available, the source
 *    must call notify_queue_not_empty() again. If the destination receives a
 *    NULL return from dequeue, it does not need to query the queue again until
 *    a notify_queue_not_empty() call is received from the source.
 *
 * 4. If the destination calls buffer_count() and receives 0, this does not mean
 *    that the source will provide a notify_queue_not_empty() call. The source
 *    must only provide such a call after the destination has received a NULL
 *    from dequeue, or on initial startup.
 *
 * 5. The dequeue() call in response to notify_queue_not_empty() may be on the
 *    same thread as the notify_queue_not_empty() call. The source must not
 *    deadlock in that case.
 */

typedef struct camera2_metadata_queue_src_ops {
    /**
     * Get count of buffers in queue
     */
    int (*buffer_count)(camera2_metadata_queue_src_ops *q);

    /**
     * Get a metadata buffer from the source. Returns OK if a request is
     * available, placing a pointer to it in next_request.
     */
    int (*dequeue)(camera2_metadata_queue_src_ops *q,
            camera_metadata_t **buffer);
    /**
     * Return a metadata buffer to the source once it has been used
     */
    int (*free)(camera2_metadata_queue_src_ops *q,
            camera_metadata_t *old_buffer);

} camera2_metadata_queue_src_ops_t;

typedef struct camera2_metadata_queue_dst_ops {
    /**
     * Notify destination that the queue is no longer empty
     */
    int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *);

} camera2_metadata_queue_dst_ops_t;

/* Defined in camera_metadata.h */
typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;

/**
 * Asynchronous notification callback from the HAL, fired for various
 * reasons. Only for information independent of frame capture, or that require
 * specific timing.
 */
typedef void (*camera2_notify_callback)(int32_t msg_type,
        int32_t ext1,
        int32_t ext2,
        void *user);

/**
 * Possible message types for camera2_notify_callback
 */
enum {
    /**
     * A serious error has occurred. Argument ext1 contains the error code, and
     * ext2 and user contain any error-specific information.
     */
    CAMERA2_MSG_ERROR   = 0x0001,
    /**
     * The exposure of a given request has begun. Argument ext1 contains the
     * request id.
     */
    CAMERA2_MSG_SHUTTER = 0x0002
};

/**
 * Error codes for CAMERA_MSG_ERROR
 */
enum {
    /**
     * A serious failure occured. Camera device may not work without reboot, and
     * no further frames or buffer streams will be produced by the
     * device. Device should be treated as closed.
     */
    CAMERA2_MSG_ERROR_HARDWARE_FAULT = 0x0001,
    /**
     * A serious failure occured. No further frames or buffer streams will be
     * produced by the device. Device should be treated as closed. The client
     * must reopen the device to use it again.
     */
    CAMERA2_MSG_ERROR_DEVICE_FAULT =   0x0002,
    /**
     * The camera service has failed. Device should be treated as released. The client
     * must reopen the device to use it again.
     */
    CAMERA2_MSG_ERROR_SERVER_FAULT =   0x0003
};

typedef struct camera2_device_ops {
    /**
     * Input request queue methods
     */
    int (*set_request_queue_src_ops)(struct camera2_device *,
            camera2_metadata_queue_src_ops *queue_src_ops);

    int (*get_request_queue_dst_ops)(struct camera2_device *,
            camera2_metadata_queue_dst_ops **queue_dst_ops);

    /**
     * Input reprocessing queue methods
     */
    int (*set_reprocess_queue_ops)(struct camera2_device *,
            camera2_metadata_queue_src_ops *queue_src_ops);

    int (*get_reprocess_queue_dst_ops)(struct camera2_device *,
            camera2_metadata_queue_dst_ops **queue_dst_ops);

    /**
     * Output frame queue methods
     */
    int (*set_frame_queue_dst_ops)(struct camera2_device *,
            camera2_metadata_queue_dst_ops *queue_dst_ops);

    int (*get_frame_queue_src_ops)(struct camera2_device *,
            camera2_metadata_queue_src_ops **queue_dst_ops);

    /**
     * Pass in notification methods
     */
    int (*set_notify_callback)(struct camera2_device *,
            camera2_notify_callback notify_cb);

    /**
     * Number of camera frames being processed by the device
     * at the moment (frames that have had their request dequeued,
     * but have not yet been enqueued onto output pipeline(s) )
     */
    int (*get_in_progress_count)(struct camera2_device *);

    /**
     * Flush all in-progress captures. This includes all dequeued requests
     * (regular or reprocessing) that have not yet placed any outputs into a
     * stream or the frame queue. Partially completed captures must be completed
     * normally. No new requests may be dequeued from the request or
     * reprocessing queues until the flush completes.
     */
    int (*flush_captures_in_progress)(struct camera2_device *);

    /**
     * Camera stream management
     */

    /**
     * Operations on the input reprocessing stream
     */
    int (*get_reprocess_stream_ops)(struct camera2_device *,
            camera2_stream_ops_t **stream_ops);

    /**
     * Get the number of streams that can be simultaneously allocated.
     * A request may include any allocated pipeline for its output, without
     * causing a substantial delay in frame production.
     */
    int (*get_stream_slot_count)(struct camera2_device *);

    /**
     * Allocate a new stream for use. Requires specifying which pipeline slot
     * to use. Specifies the buffer width, height, and format.
     * Error conditions:
     *  - Allocating an already-allocated slot without first releasing it
     *  - Requesting a width/height/format combination not listed as supported
     *  - Requesting a pipeline slot >= pipeline slot count.
     */
    int (*allocate_stream)(
        struct camera2_device *,
        uint32_t stream_slot,
        uint32_t width,
        uint32_t height,
        uint32_t format,
        camera2_stream_ops_t *camera2_stream_ops);

    /**
     * Release a stream. Returns an error if called when
     * get_in_progress_count is non-zero, or if the pipeline slot is not
     * allocated.
     */
    int (*release_stream)(
        struct camera2_device *,
        uint32_t stream_slot);

    /**
     * Get methods to query for vendor extension metadata tag infomation. May
     * set ops to NULL if no vendor extension tags are defined.
     */
    int (*get_metadata_vendor_tag_ops)(struct camera2_device*,
            vendor_tag_query_ops_t **ops);

    /**
     * Release the camera hardware.  Requests that are in flight will be
     * canceled. No further buffers will be pushed into any allocated pipelines
     * once this call returns.
     */
    void (*release)(struct camera2_device *);

    /**
     * Dump state of the camera hardware
     */
    int (*dump)(struct camera2_device *, int fd);

} camera2_device_ops_t;

typedef struct camera2_device {
    /**
     * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify
     * this device as implementing version 2.0 of the camera device HAL.
     */
    hw_device_t common;
    camera2_device_ops_t *ops;
    void *priv;
} camera2_device_t;

__END_DECLS

#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */