CameraDeviceBase.h revision cb0652e5a850b2fcd919e977247e87239efaf70e 
1/*
2 * Copyright (C) 2013 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_SERVERS_CAMERA_CAMERADEVICEBASE_H
18#define ANDROID_SERVERS_CAMERA_CAMERADEVICEBASE_H
19
20#include <utils/RefBase.h>
21#include <utils/String8.h>
22#include <utils/String16.h>
23#include <utils/Vector.h>
24#include <utils/Timers.h>
25#include <utils/List.h>
26
27#include <camera/camera2/ICameraDeviceCallbacks.h>
28#include "hardware/camera2.h"
29#include "camera/CameraMetadata.h"
30#include "camera/CaptureResult.h"
31
32namespace android {
33
34/**
35 * Base interface for version >= 2 camera device classes, which interface to
36 * camera HAL device versions >= 2.
37 */
38class CameraDeviceBase : public virtual RefBase {
39  public:
40    virtual ~CameraDeviceBase();
41
42    /**
43     * The device's camera ID
44     */
45    virtual int      getId() const = 0;
46
47    virtual status_t initialize(camera_module_t *module) = 0;
48    virtual status_t disconnect() = 0;
49
50    virtual status_t dump(int fd, const Vector<String16> &args) = 0;
51
52    /**
53     * The device's static characteristics metadata buffer
54     */
55    virtual const CameraMetadata& info() const = 0;
56
57    /**
58     * Submit request for capture. The CameraDevice takes ownership of the
59     * passed-in buffer.
60     * Output lastFrameNumber is the expected frame number of this request.
61     */
62    virtual status_t capture(CameraMetadata &request, int64_t *lastFrameNumber = NULL) = 0;
63
64    /**
65     * Submit a list of requests.
66     * Output lastFrameNumber is the expected last frame number of the list of requests.
67     */
68    virtual status_t captureList(const List<const CameraMetadata> &requests,
69                                 int64_t *lastFrameNumber = NULL) = 0;
70
71    /**
72     * Submit request for streaming. The CameraDevice makes a copy of the
73     * passed-in buffer and the caller retains ownership.
74     * Output lastFrameNumber is the last frame number of the previous streaming request.
75     */
76    virtual status_t setStreamingRequest(const CameraMetadata &request,
77                                         int64_t *lastFrameNumber = NULL) = 0;
78
79    /**
80     * Submit a list of requests for streaming.
81     * Output lastFrameNumber is the last frame number of the previous streaming request.
82     */
83    virtual status_t setStreamingRequestList(const List<const CameraMetadata> &requests,
84                                             int64_t *lastFrameNumber = NULL) = 0;
85
86    /**
87     * Clear the streaming request slot.
88     * Output lastFrameNumber is the last frame number of the previous streaming request.
89     */
90    virtual status_t clearStreamingRequest(int64_t *lastFrameNumber = NULL) = 0;
91
92    /**
93     * Wait until a request with the given ID has been dequeued by the
94     * HAL. Returns TIMED_OUT if the timeout duration is reached. Returns
95     * immediately if the latest request received by the HAL has this id.
96     */
97    virtual status_t waitUntilRequestReceived(int32_t requestId,
98            nsecs_t timeout) = 0;
99
100    /**
101     * Create an output stream of the requested size and format.
102     *
103     * If format is CAMERA2_HAL_PIXEL_FORMAT_OPAQUE, then the HAL device selects
104     * an appropriate format; it can be queried with getStreamInfo.
105     *
106     * If format is HAL_PIXEL_FORMAT_COMPRESSED, the size parameter must be
107     * equal to the size in bytes of the buffers to allocate for the stream. For
108     * other formats, the size parameter is ignored.
109     */
110    virtual status_t createStream(sp<ANativeWindow> consumer,
111            uint32_t width, uint32_t height, int format, size_t size,
112            int *id) = 0;
113
114    /**
115     * Create an input reprocess stream that uses buffers from an existing
116     * output stream.
117     */
118    virtual status_t createReprocessStreamFromStream(int outputId, int *id) = 0;
119
120    /**
121     * Get information about a given stream.
122     */
123    virtual status_t getStreamInfo(int id,
124            uint32_t *width, uint32_t *height, uint32_t *format) = 0;
125
126    /**
127     * Set stream gralloc buffer transform
128     */
129    virtual status_t setStreamTransform(int id, int transform) = 0;
130
131    /**
132     * Delete stream. Must not be called if there are requests in flight which
133     * reference that stream.
134     */
135    virtual status_t deleteStream(int id) = 0;
136
137    /**
138     * Delete reprocess stream. Must not be called if there are requests in
139     * flight which reference that stream.
140     */
141    virtual status_t deleteReprocessStream(int id) = 0;
142
143    /**
144     * Create a metadata buffer with fields that the HAL device believes are
145     * best for the given use case
146     */
147    virtual status_t createDefaultRequest(int templateId,
148            CameraMetadata *request) = 0;
149
150    /**
151     * Wait until all requests have been processed. Returns INVALID_OPERATION if
152     * the streaming slot is not empty, or TIMED_OUT if the requests haven't
153     * finished processing in 10 seconds.
154     */
155    virtual status_t waitUntilDrained() = 0;
156
157    /**
158     * Abstract class for HAL notification listeners
159     */
160    class NotificationListener {
161      public:
162        // The set of notifications is a merge of the notifications required for
163        // API1 and API2.
164
165        // Required for API 1 and 2
166        virtual void notifyError(ICameraDeviceCallbacks::CameraErrorCode errorCode,
167                                 const CaptureResultExtras &resultExtras) = 0;
168
169        // Required only for API2
170        virtual void notifyIdle() = 0;
171        virtual void notifyShutter(const CaptureResultExtras &resultExtras,
172                nsecs_t timestamp) = 0;
173
174        // Required only for API1
175        virtual void notifyAutoFocus(uint8_t newState, int triggerId) = 0;
176        virtual void notifyAutoExposure(uint8_t newState, int triggerId) = 0;
177        virtual void notifyAutoWhitebalance(uint8_t newState,
178                int triggerId) = 0;
179      protected:
180        virtual ~NotificationListener();
181    };
182
183    /**
184     * Connect HAL notifications to a listener. Overwrites previous
185     * listener. Set to NULL to stop receiving notifications.
186     */
187    virtual status_t setNotifyCallback(NotificationListener *listener) = 0;
188
189    /**
190     * Whether the device supports calling notifyAutofocus, notifyAutoExposure,
191     * and notifyAutoWhitebalance; if this returns false, the client must
192     * synthesize these notifications from received frame metadata.
193     */
194    virtual bool     willNotify3A() = 0;
195
196    /**
197     * Wait for a new frame to be produced, with timeout in nanoseconds.
198     * Returns TIMED_OUT when no frame produced within the specified duration
199     * May be called concurrently to most methods, except for getNextFrame
200     */
201    virtual status_t waitForNextFrame(nsecs_t timeout) = 0;
202
203    /**
204     * Get next capture result frame from the result queue. Returns NOT_ENOUGH_DATA
205     * if the queue is empty; caller takes ownership of the metadata buffer inside
206     * the capture result object's metadata field.
207     * May be called concurrently to most methods, except for waitForNextFrame.
208     */
209    virtual status_t getNextResult(CaptureResult *frame) = 0;
210
211    /**
212     * Trigger auto-focus. The latest ID used in a trigger autofocus or cancel
213     * autofocus call will be returned by the HAL in all subsequent AF
214     * notifications.
215     */
216    virtual status_t triggerAutofocus(uint32_t id) = 0;
217
218    /**
219     * Cancel auto-focus. The latest ID used in a trigger autofocus/cancel
220     * autofocus call will be returned by the HAL in all subsequent AF
221     * notifications.
222     */
223    virtual status_t triggerCancelAutofocus(uint32_t id) = 0;
224
225    /**
226     * Trigger pre-capture metering. The latest ID used in a trigger pre-capture
227     * call will be returned by the HAL in all subsequent AE and AWB
228     * notifications.
229     */
230    virtual status_t triggerPrecaptureMetering(uint32_t id) = 0;
231
232    /**
233     * Abstract interface for clients that want to listen to reprocess buffer
234     * release events
235     */
236    struct BufferReleasedListener : public virtual RefBase {
237        virtual void onBufferReleased(buffer_handle_t *handle) = 0;
238    };
239
240    /**
241     * Push a buffer to be reprocessed into a reprocessing stream, and
242     * provide a listener to call once the buffer is returned by the HAL
243     */
244    virtual status_t pushReprocessBuffer(int reprocessStreamId,
245            buffer_handle_t *buffer, wp<BufferReleasedListener> listener) = 0;
246
247    /**
248     * Flush all pending and in-flight requests. Blocks until flush is
249     * complete.
250     * Output lastFrameNumber is the last frame number of the previous streaming request.
251     */
252    virtual status_t flush(int64_t *lastFrameNumber = NULL) = 0;
253
254};
255
256}; // namespace android
257
258#endif
259