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#include "common/CameraModule.h"
33#include "gui/IGraphicBufferProducer.h"
34
35namespace android {
36
37/**
38 * Base interface for version >= 2 camera device classes, which interface to
39 * camera HAL device versions >= 2.
40 */
41class CameraDeviceBase : public virtual RefBase {
42  public:
43    virtual ~CameraDeviceBase();
44
45    /**
46     * The device's camera ID
47     */
48    virtual int      getId() const = 0;
49
50    virtual status_t initialize(CameraModule *module) = 0;
51    virtual status_t disconnect() = 0;
52
53    virtual status_t dump(int fd, const Vector<String16> &args) = 0;
54
55    /**
56     * The device's static characteristics metadata buffer
57     */
58    virtual const CameraMetadata& info() const = 0;
59
60    /**
61     * Submit request for capture. The CameraDevice takes ownership of the
62     * passed-in buffer.
63     * Output lastFrameNumber is the expected frame number of this request.
64     */
65    virtual status_t capture(CameraMetadata &request, int64_t *lastFrameNumber = NULL) = 0;
66
67    /**
68     * Submit a list of requests.
69     * Output lastFrameNumber is the expected last frame number of the list of requests.
70     */
71    virtual status_t captureList(const List<const CameraMetadata> &requests,
72                                 int64_t *lastFrameNumber = NULL) = 0;
73
74    /**
75     * Submit request for streaming. The CameraDevice makes a copy of the
76     * passed-in buffer and the caller retains ownership.
77     * Output lastFrameNumber is the last frame number of the previous streaming request.
78     */
79    virtual status_t setStreamingRequest(const CameraMetadata &request,
80                                         int64_t *lastFrameNumber = NULL) = 0;
81
82    /**
83     * Submit a list of requests for streaming.
84     * Output lastFrameNumber is the last frame number of the previous streaming request.
85     */
86    virtual status_t setStreamingRequestList(const List<const CameraMetadata> &requests,
87                                             int64_t *lastFrameNumber = NULL) = 0;
88
89    /**
90     * Clear the streaming request slot.
91     * Output lastFrameNumber is the last frame number of the previous streaming request.
92     */
93    virtual status_t clearStreamingRequest(int64_t *lastFrameNumber = NULL) = 0;
94
95    /**
96     * Wait until a request with the given ID has been dequeued by the
97     * HAL. Returns TIMED_OUT if the timeout duration is reached. Returns
98     * immediately if the latest request received by the HAL has this id.
99     */
100    virtual status_t waitUntilRequestReceived(int32_t requestId,
101            nsecs_t timeout) = 0;
102
103    /**
104     * Create an output stream of the requested size, format, rotation and dataspace
105     *
106     * For HAL_PIXEL_FORMAT_BLOB formats, the width and height should be the
107     * logical dimensions of the buffer, not the number of bytes.
108     */
109    virtual status_t createStream(sp<Surface> consumer,
110            uint32_t width, uint32_t height, int format,
111            android_dataspace dataSpace, camera3_stream_rotation_t rotation, int *id) = 0;
112
113    /**
114     * Create an input stream of width, height, and format.
115     *
116     * Return value is the stream ID if non-negative and an error if negative.
117     */
118    virtual status_t createInputStream(uint32_t width, uint32_t height,
119            int32_t format, /*out*/ int32_t *id) = 0;
120
121    /**
122     * Create an input reprocess stream that uses buffers from an existing
123     * output stream.
124     */
125    virtual status_t createReprocessStreamFromStream(int outputId, int *id) = 0;
126
127    /**
128     * Get information about a given stream.
129     */
130    virtual status_t getStreamInfo(int id,
131            uint32_t *width, uint32_t *height,
132            uint32_t *format, android_dataspace *dataSpace) = 0;
133
134    /**
135     * Set stream gralloc buffer transform
136     */
137    virtual status_t setStreamTransform(int id, int transform) = 0;
138
139    /**
140     * Delete stream. Must not be called if there are requests in flight which
141     * reference that stream.
142     */
143    virtual status_t deleteStream(int id) = 0;
144
145    /**
146     * Delete reprocess stream. Must not be called if there are requests in
147     * flight which reference that stream.
148     */
149    virtual status_t deleteReprocessStream(int id) = 0;
150
151    /**
152     * Take the currently-defined set of streams and configure the HAL to use
153     * them. This is a long-running operation (may be several hundered ms).
154     *
155     * The device must be idle (see waitUntilDrained) before calling this.
156     *
157     * Returns OK on success; otherwise on error:
158     * - BAD_VALUE if the set of streams was invalid (e.g. fmts or sizes)
159     * - INVALID_OPERATION if the device was in the wrong state
160     */
161    virtual status_t configureStreams(bool isConstrainedHighSpeed = false) = 0;
162
163    // get the buffer producer of the input stream
164    virtual status_t getInputBufferProducer(
165            sp<IGraphicBufferProducer> *producer) = 0;
166
167    /**
168     * Create a metadata buffer with fields that the HAL device believes are
169     * best for the given use case
170     */
171    virtual status_t createDefaultRequest(int templateId,
172            CameraMetadata *request) = 0;
173
174    /**
175     * Wait until all requests have been processed. Returns INVALID_OPERATION if
176     * the streaming slot is not empty, or TIMED_OUT if the requests haven't
177     * finished processing in 10 seconds.
178     */
179    virtual status_t waitUntilDrained() = 0;
180
181    /**
182     * Get Jpeg buffer size for a given jpeg resolution.
183     * Negative values are error codes.
184     */
185    virtual ssize_t getJpegBufferSize(uint32_t width, uint32_t height) const = 0;
186
187    /**
188     * Abstract class for HAL notification listeners
189     */
190    class NotificationListener {
191      public:
192        // The set of notifications is a merge of the notifications required for
193        // API1 and API2.
194
195        // Required for API 1 and 2
196        virtual void notifyError(ICameraDeviceCallbacks::CameraErrorCode errorCode,
197                                 const CaptureResultExtras &resultExtras) = 0;
198
199        // Required only for API2
200        virtual void notifyIdle() = 0;
201        virtual void notifyShutter(const CaptureResultExtras &resultExtras,
202                nsecs_t timestamp) = 0;
203        virtual void notifyPrepared(int streamId) = 0;
204
205        // Required only for API1
206        virtual void notifyAutoFocus(uint8_t newState, int triggerId) = 0;
207        virtual void notifyAutoExposure(uint8_t newState, int triggerId) = 0;
208        virtual void notifyAutoWhitebalance(uint8_t newState,
209                int triggerId) = 0;
210      protected:
211        virtual ~NotificationListener();
212    };
213
214    /**
215     * Connect HAL notifications to a listener. Overwrites previous
216     * listener. Set to NULL to stop receiving notifications.
217     */
218    virtual status_t setNotifyCallback(NotificationListener *listener) = 0;
219
220    /**
221     * Whether the device supports calling notifyAutofocus, notifyAutoExposure,
222     * and notifyAutoWhitebalance; if this returns false, the client must
223     * synthesize these notifications from received frame metadata.
224     */
225    virtual bool     willNotify3A() = 0;
226
227    /**
228     * Wait for a new frame to be produced, with timeout in nanoseconds.
229     * Returns TIMED_OUT when no frame produced within the specified duration
230     * May be called concurrently to most methods, except for getNextFrame
231     */
232    virtual status_t waitForNextFrame(nsecs_t timeout) = 0;
233
234    /**
235     * Get next capture result frame from the result queue. Returns NOT_ENOUGH_DATA
236     * if the queue is empty; caller takes ownership of the metadata buffer inside
237     * the capture result object's metadata field.
238     * May be called concurrently to most methods, except for waitForNextFrame.
239     */
240    virtual status_t getNextResult(CaptureResult *frame) = 0;
241
242    /**
243     * Trigger auto-focus. The latest ID used in a trigger autofocus or cancel
244     * autofocus call will be returned by the HAL in all subsequent AF
245     * notifications.
246     */
247    virtual status_t triggerAutofocus(uint32_t id) = 0;
248
249    /**
250     * Cancel auto-focus. The latest ID used in a trigger autofocus/cancel
251     * autofocus call will be returned by the HAL in all subsequent AF
252     * notifications.
253     */
254    virtual status_t triggerCancelAutofocus(uint32_t id) = 0;
255
256    /**
257     * Trigger pre-capture metering. The latest ID used in a trigger pre-capture
258     * call will be returned by the HAL in all subsequent AE and AWB
259     * notifications.
260     */
261    virtual status_t triggerPrecaptureMetering(uint32_t id) = 0;
262
263    /**
264     * Abstract interface for clients that want to listen to reprocess buffer
265     * release events
266     */
267    struct BufferReleasedListener : public virtual RefBase {
268        virtual void onBufferReleased(buffer_handle_t *handle) = 0;
269    };
270
271    /**
272     * Push a buffer to be reprocessed into a reprocessing stream, and
273     * provide a listener to call once the buffer is returned by the HAL
274     */
275    virtual status_t pushReprocessBuffer(int reprocessStreamId,
276            buffer_handle_t *buffer, wp<BufferReleasedListener> listener) = 0;
277
278    /**
279     * Flush all pending and in-flight requests. Blocks until flush is
280     * complete.
281     * Output lastFrameNumber is the last frame number of the previous streaming request.
282     */
283    virtual status_t flush(int64_t *lastFrameNumber = NULL) = 0;
284
285    /**
286     * Prepare stream by preallocating buffers for it asynchronously.
287     * Calls notifyPrepared() once allocation is complete.
288     */
289    virtual status_t prepare(int streamId) = 0;
290
291    /**
292     * Free stream resources by dumping its unused gralloc buffers.
293     */
294    virtual status_t tearDown(int streamId) = 0;
295
296    /**
297     * Prepare stream by preallocating up to maxCount buffers for it asynchronously.
298     * Calls notifyPrepared() once allocation is complete.
299     */
300    virtual status_t prepare(int maxCount, int streamId) = 0;
301
302    /**
303     * Get the HAL device version.
304     */
305    virtual uint32_t getDeviceVersion() = 0;
306};
307
308}; // namespace android
309
310#endif
311