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