camera2.h revision ddc026e39344169f64f4696174a4d1269d069557 
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
44/**
45 * Output image stream queue management
46 */
47
48typedef struct camera2_stream_ops {
49    int (*dequeue_buffer)(struct camera2_stream_ops* w,
50                          buffer_handle_t** buffer, int *stride);
51    int (*enqueue_buffer)(struct camera2_stream_ops* w,
52                buffer_handle_t* buffer);
53    int (*cancel_buffer)(struct camera2_stream_ops* w,
54                buffer_handle_t* buffer);
55    int (*set_buffer_count)(struct camera2_stream_ops* w, int count);
56    int (*set_crop)(struct camera2_stream_ops *w,
57                int left, int top, int right, int bottom);
58    // Timestamps are measured in nanoseconds, and must be comparable
59    // and monotonically increasing between two frames in the same
60    // preview stream. They do not need to be comparable between
61    // consecutive or parallel preview streams, cameras, or app runs.
62    // The timestamp must be the time at the start of image exposure.
63    int (*set_timestamp)(struct camera2_stream_ops *w, int64_t timestamp);
64    int (*set_usage)(struct camera2_stream_ops* w, int usage);
65    int (*set_swap_interval)(struct camera2_stream_ops *w, int interval);
66    int (*get_min_undequeued_buffer_count)(const struct camera2_stream_ops *w,
67                int *count);
68    int (*lock_buffer)(struct camera2_stream_ops* w,
69                buffer_handle_t* buffer);
70} camera2_stream_ops_t;
71
72/**
73 * Metadata queue management, used for requests sent to HAL module, and for
74 * frames produced by the HAL.
75 */
76
77typedef struct camera2_metadata_queue_src_ops {
78    /**
79     * Get count of buffers in queue
80     */
81    int (*buffer_count)(camera2_metadata_queue_src_ops *q);
82
83    /**
84     * Get a metadata buffer from the source. Returns OK if a request is
85     * available, placing a pointer to it in next_request.
86     */
87    int (*dequeue)(camera2_metadata_queue_src_ops *q,
88            camera_metadata_t **buffer);
89    /**
90     * Return a metadata buffer to the source once it has been used
91     */
92    int (*free)(camera2_metadata_queue_src_ops *q,
93            camera_metadata_t *old_buffer);
94
95} camera2_metadata_queue_src_ops_t;
96
97typedef struct camera2_metadata_queue_dst_ops {
98    /**
99     * Notify destination that the queue is no longer empty
100     */
101    int (*notify_queue_not_empty)(struct camera2_metadata_queue_dst_ops *);
102} camera2_metadata_queue_dst_ops_t;
103
104/* Defined in camera_metadata.h */
105typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
106
107/**
108 * Asynchronous notification callback from the HAL, fired for various
109 * reasons. Only for information independent of frame capture, or that require
110 * specific timing.
111 */
112typedef void (*camera2_notify_callback)(int32_t msg_type,
113        int32_t ext1,
114        int32_t ext2,
115        void *user);
116
117/**
118 * Possible message types for camera2_notify_callback
119 */
120enum {
121    /**
122     * A serious error has occurred. Argument ext1 contains the error code, and
123     * ext2 and user contain any error-specific information.
124     */
125    CAMERA2_MSG_ERROR   = 0x0001,
126    /**
127     * The exposure of a given request has begun. Argument ext1 contains the
128     * request id.
129     */
130    CAMERA2_MSG_SHUTTER = 0x0002
131};
132
133/**
134 * Error codes for CAMERA_MSG_ERROR
135 */
136enum {
137    /**
138     * A serious failure occured. Camera device may not work without reboot, and
139     * no further frames or buffer streams will be produced by the
140     * device. Device should be treated as closed.
141     */
142    CAMERA2_MSG_ERROR_HARDWARE_FAULT = 0x0001,
143    /**
144     * A serious failure occured. No further frames or buffer streams will be
145     * produced by the device. Device should be treated as closed. The client
146     * must reopen the device to use it again.
147     */
148    CAMERA2_MSG_ERROR_DEVICE_FAULT =   0x0002,
149    /**
150     * The camera service has failed. Device should be treated as released. The client
151     * must reopen the device to use it again.
152     */
153    CAMERA2_MSG_ERROR_SERVER_FAULT =   0x0003
154};
155
156
157struct camera2_device;
158typedef struct camera2_device_ops {
159    /**
160     * Input request queue methods
161     */
162    int (*set_request_queue_ops)(struct camera2_device *,
163            camera2_metadata_queue_src_ops *request_queue_src_ops);
164
165    camera2_metadata_queue_dst_ops_t *request_queue_dst_ops;
166
167    /**
168     * Input reprocessing queue methods
169     */
170    int (*set_reprocess_queue_ops)(struct camera2_device *,
171            camera2_metadata_queue_src_ops *reprocess_queue_src_ops);
172
173    camera2_metadata_queue_dst_ops_t *reprocess_queue_dst_ops;
174
175    /**
176     * Output frame queue methods
177     */
178    int (*set_frame_queue_ops)(struct camera2_device *,
179            camera2_metadata_queue_dst_ops *frame_queue_dst_ops);
180
181    camera2_metadata_queue_src_ops_t *frame_queue_src_ops;
182
183    /**
184     * Pass in notification methods
185     */
186    int (*set_notify_callback)(struct camera2_device *,
187            camera2_notify_callback notify_cb);
188
189    /**
190     * Number of camera frames being processed by the device
191     * at the moment (frames that have had their request dequeued,
192     * but have not yet been enqueued onto output pipeline(s) )
193     */
194    int (*get_in_progress_count)(struct camera2_device *);
195
196    /**
197     * Flush all in-progress captures. This includes all dequeued requests
198     * (regular or reprocessing) that have not yet placed any outputs into a
199     * stream or the frame queue. Partially completed captures must be completed
200     * normally. No new requests may be dequeued from the request or
201     * reprocessing queues until the flush completes.
202     */
203    int (*flush_captures_in_progress)(struct camera2_device *);
204
205    /**
206     * Camera stream management
207     */
208
209    /**
210     * Operations on the input reprocessing stream
211     */
212    camera2_stream_ops_t *reprocess_stream_ops;
213
214    /**
215     * Get the number of streams that can be simultaneously allocated.
216     * A request may include any allocated pipeline for its output, without
217     * causing a substantial delay in frame production.
218     */
219    int (*get_stream_slot_count)(struct camera2_device *);
220
221    /**
222     * Allocate a new stream for use. Requires specifying which pipeline slot
223     * to use. Specifies the buffer width, height, and format.
224     * Error conditions:
225     *  - Allocating an already-allocated slot without first releasing it
226     *  - Requesting a width/height/format combination not listed as supported
227     *  - Requesting a pipeline slot >= pipeline slot count.
228     */
229    int (*allocate_stream)(
230        struct camera2_device *,
231        uint32_t stream_slot,
232        uint32_t width,
233        uint32_t height,
234        int format,
235        camera2_stream_ops_t *camera2_stream_ops);
236
237    /**
238     * Release a stream. Returns an error if called when
239     * get_in_progress_count is non-zero, or if the pipeline slot is not
240     * allocated.
241     */
242    int (*release_stream)(
243        struct camera2_device *,
244        uint32_t stream_slot);
245
246    /**
247     * Release the camera hardware.  Requests that are in flight will be
248     * canceled. No further buffers will be pushed into any allocated pipelines
249     * once this call returns.
250     */
251    void (*release)(struct camera2_device *);
252
253    /**
254     * Methods to query for vendor extension metadata tag infomation. May be NULL
255     * if no vendor extension tags are defined.
256     */
257    vendor_tag_query_ops *camera_metadata_vendor_tag_ops;
258
259    /**
260     * Dump state of the camera hardware
261     */
262    int (*dump)(struct camera2_device *, int fd);
263
264} camera2_device_ops_t;
265
266typedef struct camera2_device {
267    /**
268     * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify
269     * this device as implementing version 2.0 of the camera device HAL.
270     */
271    hw_device_t common;
272    camera2_device_ops_t *ops;
273    void *priv;
274} camera2_device_t;
275
276__END_DECLS
277
278#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */
279