1/*
2 * Copyright (C) 2012 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#ifndef ANDROID_INCLUDE_CAMERA2_H
18#define ANDROID_INCLUDE_CAMERA2_H
19
20#include "camera_common.h"
21
22/**
23 * Camera device HAL 2.0 [ CAMERA_DEVICE_API_VERSION_2_0 ]
24 *
25 * EXPERIMENTAL.
26 *
27 * Supports both the android.hardware.ProCamera and
28 * android.hardware.Camera APIs.
29 *
30 * Camera devices that support this version of the HAL must return
31 * CAMERA_DEVICE_API_VERSION_2_0 in camera_device_t.common.version and in
32 * camera_info_t.device_version (from camera_module_t.get_camera_info).
33 *
34 * Camera modules that may contain version 2.0 devices must implement at least
35 * version 2.0 of the camera module interface (as defined by
36 * camera_module_t.common.module_api_version).
37 *
38 * See camera_common.h for more details.
39 *
40 */
41
42__BEGIN_DECLS
43
44struct camera2_device;
45
46/**
47 * Output image stream queue management
48 */
49
50typedef struct camera2_stream_ops {
51    int (*dequeue_buffer)(struct camera2_stream_ops* w,
52                          buffer_handle_t** buffer, int *stride);
53    int (*enqueue_buffer)(struct camera2_stream_ops* w,
54                buffer_handle_t* buffer);
55    int (*cancel_buffer)(struct camera2_stream_ops* w,
56                buffer_handle_t* buffer);
57    int (*set_buffer_count)(struct camera2_stream_ops* w, int count);
58    int (*set_buffers_geometry)(struct camera2_stream_ops* pw,
59                int w, int h, int format);
60    int (*set_crop)(struct camera2_stream_ops *w,
61                int left, int top, int right, int bottom);
62    // Timestamps are measured in nanoseconds, and must be comparable
63    // and monotonically increasing between two frames in the same
64    // preview stream. They do not need to be comparable between
65    // consecutive or parallel preview streams, cameras, or app runs.
66    // The timestamp must be the time at the start of image exposure.
67    int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp);
68    int (*set_usage)(struct camera2_stream_ops* w, int usage);
69    int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w,
70                int *count);
71    int (*lock_buffer)(struct camera2_stream_ops* w,
72                buffer_handle_t* buffer);
73} camera2_stream_ops_t;
74
75/**
76 * Metadata queue management, used for requests sent to HAL module, and for
77 * frames produced by the HAL.
78 *
79 * Queue protocol:
80 *
81 * The source holds the queue and its contents. At start, the queue is empty.
82 *
83 * 1. When the first metadata buffer is placed into the queue, the source must
84 *    signal the destination by calling notify_queue_not_empty().
85 *
86 * 2. After receiving notify_queue_not_empty, the destination must call
87 *    dequeue() once it's ready to handle the next buffer.
88 *
89 * 3. Once the destination has processed a buffer, it should try to dequeue
90 *    another buffer. If there are no more buffers available, dequeue() will
91 *    return NULL. In this case, when a buffer becomes available, the source
92 *    must call notify_queue_not_empty() again. If the destination receives a
93 *    NULL return from dequeue, it does not need to query the queue again until
94 *    a notify_queue_not_empty() call is received from the source.
95 *
96 * 4. If the destination calls buffer_count() and receives 0, this does not mean
97 *    that the source will provide a notify_queue_not_empty() call. The source
98 *    must only provide such a call after the destination has received a NULL
99 *    from dequeue, or on initial startup.
100 *
101 * 5. The dequeue() call in response to notify_queue_not_empty() may be on the
102 *    same thread as the notify_queue_not_empty() call. The source must not
103 *    deadlock in that case.
104 */
105
106typedef struct camera2_metadata_queue_src_ops {
107    /**
108     * Get count of buffers in queue
109     */
110    int (*buffer_count)(camera2_metadata_queue_src_ops *q);
111
112    /**
113     * Get a metadata buffer from the source. Returns OK if a request is
114     * available, placing a pointer to it in next_request.
115     */
116    int (*dequeue)(camera2_metadata_queue_src_ops *q,
117            camera_metadata_t **buffer);
118    /**
119     * Return a metadata buffer to the source once it has been used
120     */
121    int (*free)(camera2_metadata_queue_src_ops *q,
122            camera_metadata_t *old_buffer);
123
124} camera2_metadata_queue_src_ops_t;
125
126typedef struct camera2_metadata_queue_dst_ops {
127    /**
128     * Notify destination that the queue is no longer empty
129     */
130    int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *);
131
132} camera2_metadata_queue_dst_ops_t;
133
134/* Defined in camera_metadata.h */
135typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
136
137/**
138 * Asynchronous notification callback from the HAL, fired for various
139 * reasons. Only for information independent of frame capture, or that require
140 * specific timing.
141 */
142typedef void (*camera2_notify_callback)(int32_t msg_type,
143        int32_t ext1,
144        int32_t ext2,
145        void *user);
146
147/**
148 * Possible message types for camera2_notify_callback
149 */
150enum {
151    /**
152     * A serious error has occurred. Argument ext1 contains the error code, and
153     * ext2 and user contain any error-specific information.
154     */
155    CAMERA2_MSG_ERROR   = 0x0001,
156    /**
157     * The exposure of a given request has begun. Argument ext1 contains the
158     * request id.
159     */
160    CAMERA2_MSG_SHUTTER = 0x0002
161};
162
163/**
164 * Error codes for CAMERA_MSG_ERROR
165 */
166enum {
167    /**
168     * A serious failure occured. Camera device may not work without reboot, and
169     * no further frames or buffer streams will be produced by the
170     * device. Device should be treated as closed.
171     */
172    CAMERA2_MSG_ERROR_HARDWARE_FAULT = 0x0001,
173    /**
174     * A serious failure occured. No further frames or buffer streams will be
175     * produced by the device. Device should be treated as closed. The client
176     * must reopen the device to use it again.
177     */
178    CAMERA2_MSG_ERROR_DEVICE_FAULT =   0x0002,
179    /**
180     * The camera service has failed. Device should be treated as released. The client
181     * must reopen the device to use it again.
182     */
183    CAMERA2_MSG_ERROR_SERVER_FAULT =   0x0003
184};
185
186typedef struct camera2_device_ops {
187    /**
188     * Input request queue methods
189     */
190    int (*set_request_queue_src_ops)(struct camera2_device *,
191            camera2_metadata_queue_src_ops *queue_src_ops);
192
193    int (*get_request_queue_dst_ops)(struct camera2_device *,
194            camera2_metadata_queue_dst_ops **queue_dst_ops);
195
196    /**
197     * Input reprocessing queue methods
198     */
199    int (*set_reprocess_queue_ops)(struct camera2_device *,
200            camera2_metadata_queue_src_ops *queue_src_ops);
201
202    int (*get_reprocess_queue_dst_ops)(struct camera2_device *,
203            camera2_metadata_queue_dst_ops **queue_dst_ops);
204
205    /**
206     * Output frame queue methods
207     */
208    int (*set_frame_queue_dst_ops)(struct camera2_device *,
209            camera2_metadata_queue_dst_ops *queue_dst_ops);
210
211    int (*get_frame_queue_src_ops)(struct camera2_device *,
212            camera2_metadata_queue_src_ops **queue_dst_ops);
213
214    /**
215     * Pass in notification methods
216     */
217    int (*set_notify_callback)(struct camera2_device *,
218            camera2_notify_callback notify_cb);
219
220    /**
221     * Number of camera frames being processed by the device
222     * at the moment (frames that have had their request dequeued,
223     * but have not yet been enqueued onto output pipeline(s) )
224     */
225    int (*get_in_progress_count)(struct camera2_device *);
226
227    /**
228     * Flush all in-progress captures. This includes all dequeued requests
229     * (regular or reprocessing) that have not yet placed any outputs into a
230     * stream or the frame queue. Partially completed captures must be completed
231     * normally. No new requests may be dequeued from the request or
232     * reprocessing queues until the flush completes.
233     */
234    int (*flush_captures_in_progress)(struct camera2_device *);
235
236    /**
237     * Camera stream management
238     */
239
240    /**
241     * Operations on the input reprocessing stream
242     */
243    int (*get_reprocess_stream_ops)(struct camera2_device *,
244            camera2_stream_ops_t **stream_ops);
245
246    /**
247     * Get the number of streams that can be simultaneously allocated.
248     * A request may include any allocated pipeline for its output, without
249     * causing a substantial delay in frame production.
250     */
251    int (*get_stream_slot_count)(struct camera2_device *);
252
253    /**
254     * Allocate a new stream for use. Requires specifying which pipeline slot
255     * to use. Specifies the buffer width, height, and format.
256     * Error conditions:
257     *  - Allocating an already-allocated slot without first releasing it
258     *  - Requesting a width/height/format combination not listed as supported
259     *  - Requesting a pipeline slot >= pipeline slot count.
260     */
261    int (*allocate_stream)(
262        struct camera2_device *,
263        uint32_t stream_slot,
264        uint32_t width,
265        uint32_t height,
266        uint32_t format,
267        camera2_stream_ops_t *camera2_stream_ops);
268
269    /**
270     * Release a stream. Returns an error if called when
271     * get_in_progress_count is non-zero, or if the pipeline slot is not
272     * allocated.
273     */
274    int (*release_stream)(
275        struct camera2_device *,
276        uint32_t stream_slot);
277
278    /**
279     * Get methods to query for vendor extension metadata tag infomation. May
280     * set ops to NULL if no vendor extension tags are defined.
281     */
282    int (*get_metadata_vendor_tag_ops)(struct camera2_device*,
283            vendor_tag_query_ops_t **ops);
284
285    /**
286     * Release the camera hardware.  Requests that are in flight will be
287     * canceled. No further buffers will be pushed into any allocated pipelines
288     * once this call returns.
289     */
290    void (*release)(struct camera2_device *);
291
292    /**
293     * Dump state of the camera hardware
294     */
295    int (*dump)(struct camera2_device *, int fd);
296
297} camera2_device_ops_t;
298
299typedef struct camera2_device {
300    /**
301     * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify
302     * this device as implementing version 2.0 of the camera device HAL.
303     */
304    hw_device_t common;
305    camera2_device_ops_t *ops;
306    void *priv;
307} camera2_device_t;
308
309__END_DECLS
310
311#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */
312