1/*
2 * Copyright (C) 2013-2018 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 <list>
21
22#include <utils/RefBase.h>
23#include <utils/String8.h>
24#include <utils/String16.h>
25#include <utils/Vector.h>
26#include <utils/KeyedVector.h>
27#include <utils/Timers.h>
28#include <utils/List.h>
29
30#include "hardware/camera2.h"
31#include "hardware/camera3.h"
32#include "camera/CameraMetadata.h"
33#include "camera/CaptureResult.h"
34#include "gui/IGraphicBufferProducer.h"
35#include "device3/Camera3StreamInterface.h"
36#include "binder/Status.h"
37
38namespace android {
39
40class CameraProviderManager;
41
42// Mapping of output stream index to surface ids
43typedef std::unordered_map<int, std::vector<size_t> > SurfaceMap;
44
45/**
46 * Base interface for version >= 2 camera device classes, which interface to
47 * camera HAL device versions >= 2.
48 */
49class CameraDeviceBase : public virtual RefBase {
50  public:
51    virtual ~CameraDeviceBase();
52
53    /**
54     * The device's camera ID
55     */
56    virtual const String8& getId() const = 0;
57
58    /**
59     * The device vendor tag ID
60     */
61    virtual metadata_vendor_id_t getVendorTagId() const = 0;
62
63    virtual status_t initialize(sp<CameraProviderManager> manager, const String8& monitorTags) = 0;
64    virtual status_t disconnect() = 0;
65
66    virtual status_t dump(int fd, const Vector<String16> &args) = 0;
67
68    /**
69     * The device's static characteristics metadata buffer
70     */
71    virtual const CameraMetadata& info() const = 0;
72
73    struct PhysicalCameraSettings {
74        std::string cameraId;
75        CameraMetadata metadata;
76    };
77    typedef List<PhysicalCameraSettings> PhysicalCameraSettingsList;
78
79    /**
80     * Submit request for capture. The CameraDevice takes ownership of the
81     * passed-in buffer.
82     * Output lastFrameNumber is the expected frame number of this request.
83     */
84    virtual status_t capture(CameraMetadata &request, int64_t *lastFrameNumber = NULL) = 0;
85
86    /**
87     * Submit a list of requests.
88     * Output lastFrameNumber is the expected last frame number of the list of requests.
89     */
90    virtual status_t captureList(const List<const PhysicalCameraSettingsList> &requests,
91                                 const std::list<const SurfaceMap> &surfaceMaps,
92                                 int64_t *lastFrameNumber = NULL) = 0;
93
94    /**
95     * Submit request for streaming. The CameraDevice makes a copy of the
96     * passed-in buffer and the caller retains ownership.
97     * Output lastFrameNumber is the last frame number of the previous streaming request.
98     */
99    virtual status_t setStreamingRequest(const CameraMetadata &request,
100                                         int64_t *lastFrameNumber = NULL) = 0;
101
102    /**
103     * Submit a list of requests for streaming.
104     * Output lastFrameNumber is the last frame number of the previous streaming request.
105     */
106    virtual status_t setStreamingRequestList(const List<const PhysicalCameraSettingsList> &requests,
107                                             const std::list<const SurfaceMap> &surfaceMaps,
108                                             int64_t *lastFrameNumber = NULL) = 0;
109
110    /**
111     * Clear the streaming request slot.
112     * Output lastFrameNumber is the last frame number of the previous streaming request.
113     */
114    virtual status_t clearStreamingRequest(int64_t *lastFrameNumber = NULL) = 0;
115
116    /**
117     * Wait until a request with the given ID has been dequeued by the
118     * HAL. Returns TIMED_OUT if the timeout duration is reached. Returns
119     * immediately if the latest request received by the HAL has this id.
120     */
121    virtual status_t waitUntilRequestReceived(int32_t requestId,
122            nsecs_t timeout) = 0;
123
124    /**
125     * Create an output stream of the requested size, format, rotation and dataspace
126     *
127     * For HAL_PIXEL_FORMAT_BLOB formats, the width and height should be the
128     * logical dimensions of the buffer, not the number of bytes.
129     */
130    virtual status_t createStream(sp<Surface> consumer,
131            uint32_t width, uint32_t height, int format,
132            android_dataspace dataSpace, camera3_stream_rotation_t rotation, int *id,
133            const String8& physicalCameraId,
134            std::vector<int> *surfaceIds = nullptr,
135            int streamSetId = camera3::CAMERA3_STREAM_SET_ID_INVALID,
136            bool isShared = false, uint64_t consumerUsage = 0) = 0;
137
138    /**
139     * Create an output stream of the requested size, format, rotation and
140     * dataspace with a number of consumers.
141     *
142     * For HAL_PIXEL_FORMAT_BLOB formats, the width and height should be the
143     * logical dimensions of the buffer, not the number of bytes.
144     */
145    virtual status_t createStream(const std::vector<sp<Surface>>& consumers,
146            bool hasDeferredConsumer, uint32_t width, uint32_t height, int format,
147            android_dataspace dataSpace, camera3_stream_rotation_t rotation, int *id,
148            const String8& physicalCameraId,
149            std::vector<int> *surfaceIds = nullptr,
150            int streamSetId = camera3::CAMERA3_STREAM_SET_ID_INVALID,
151            bool isShared = false, uint64_t consumerUsage = 0) = 0;
152
153    /**
154     * Create an input stream of width, height, and format.
155     *
156     * Return value is the stream ID if non-negative and an error if negative.
157     */
158    virtual status_t createInputStream(uint32_t width, uint32_t height,
159            int32_t format, /*out*/ int32_t *id) = 0;
160
161    struct StreamInfo {
162        uint32_t width;
163        uint32_t height;
164
165        uint32_t format;
166        bool formatOverridden;
167        uint32_t originalFormat;
168
169        android_dataspace dataSpace;
170        bool dataSpaceOverridden;
171        android_dataspace originalDataSpace;
172
173        StreamInfo() : width(0), height(0), format(0), formatOverridden(false), originalFormat(0),
174                dataSpace(HAL_DATASPACE_UNKNOWN), dataSpaceOverridden(false),
175                originalDataSpace(HAL_DATASPACE_UNKNOWN) {}
176        /**
177         * Check whether the format matches the current or the original one in case
178         * it got overridden.
179         */
180        bool matchFormat(uint32_t clientFormat) const {
181            if ((formatOverridden && (originalFormat == clientFormat)) ||
182                    (format == clientFormat)) {
183                return true;
184            }
185            return false;
186        }
187
188        /**
189         * Check whether the dataspace matches the current or the original one in case
190         * it got overridden.
191         */
192        bool matchDataSpace(android_dataspace clientDataSpace) const {
193            if ((dataSpaceOverridden && (originalDataSpace == clientDataSpace)) ||
194                    (dataSpace == clientDataSpace)) {
195                return true;
196            }
197            return false;
198        }
199
200    };
201
202    /**
203     * Get information about a given stream.
204     */
205    virtual status_t getStreamInfo(int id, StreamInfo *streamInfo) = 0;
206
207    /**
208     * Set stream gralloc buffer transform
209     */
210    virtual status_t setStreamTransform(int id, int transform) = 0;
211
212    /**
213     * Delete stream. Must not be called if there are requests in flight which
214     * reference that stream.
215     */
216    virtual status_t deleteStream(int id) = 0;
217
218    /**
219     * Take the currently-defined set of streams and configure the HAL to use
220     * them. This is a long-running operation (may be several hundered ms).
221     *
222     * The device must be idle (see waitUntilDrained) before calling this.
223     *
224     * Returns OK on success; otherwise on error:
225     * - BAD_VALUE if the set of streams was invalid (e.g. fmts or sizes)
226     * - INVALID_OPERATION if the device was in the wrong state
227     */
228    virtual status_t configureStreams(const CameraMetadata& sessionParams,
229            int operatingMode = 0) = 0;
230
231    // get the buffer producer of the input stream
232    virtual status_t getInputBufferProducer(
233            sp<IGraphicBufferProducer> *producer) = 0;
234
235    /**
236     * Create a metadata buffer with fields that the HAL device believes are
237     * best for the given use case
238     */
239    virtual status_t createDefaultRequest(int templateId,
240            CameraMetadata *request) = 0;
241
242    /**
243     * Wait until all requests have been processed. Returns INVALID_OPERATION if
244     * the streaming slot is not empty, or TIMED_OUT if the requests haven't
245     * finished processing in 10 seconds.
246     */
247    virtual status_t waitUntilDrained() = 0;
248
249    /**
250     * Get Jpeg buffer size for a given jpeg resolution.
251     * Negative values are error codes.
252     */
253    virtual ssize_t getJpegBufferSize(uint32_t width, uint32_t height) const = 0;
254
255    /**
256     * Abstract class for HAL notification listeners
257     */
258    class NotificationListener : public virtual RefBase {
259      public:
260        // The set of notifications is a merge of the notifications required for
261        // API1 and API2.
262
263        // Required for API 1 and 2
264        virtual void notifyError(int32_t errorCode,
265                                 const CaptureResultExtras &resultExtras) = 0;
266
267        // Required only for API2
268        virtual void notifyIdle() = 0;
269        virtual void notifyShutter(const CaptureResultExtras &resultExtras,
270                nsecs_t timestamp) = 0;
271        virtual void notifyPrepared(int streamId) = 0;
272        virtual void notifyRequestQueueEmpty() = 0;
273
274        // Required only for API1
275        virtual void notifyAutoFocus(uint8_t newState, int triggerId) = 0;
276        virtual void notifyAutoExposure(uint8_t newState, int triggerId) = 0;
277        virtual void notifyAutoWhitebalance(uint8_t newState,
278                int triggerId) = 0;
279        virtual void notifyRepeatingRequestError(long lastFrameNumber) = 0;
280      protected:
281        virtual ~NotificationListener();
282    };
283
284    /**
285     * Connect HAL notifications to a listener. Overwrites previous
286     * listener. Set to NULL to stop receiving notifications.
287     */
288    virtual status_t setNotifyCallback(wp<NotificationListener> listener) = 0;
289
290    /**
291     * Whether the device supports calling notifyAutofocus, notifyAutoExposure,
292     * and notifyAutoWhitebalance; if this returns false, the client must
293     * synthesize these notifications from received frame metadata.
294     */
295    virtual bool     willNotify3A() = 0;
296
297    /**
298     * Wait for a new frame to be produced, with timeout in nanoseconds.
299     * Returns TIMED_OUT when no frame produced within the specified duration
300     * May be called concurrently to most methods, except for getNextFrame
301     */
302    virtual status_t waitForNextFrame(nsecs_t timeout) = 0;
303
304    /**
305     * Get next capture result frame from the result queue. Returns NOT_ENOUGH_DATA
306     * if the queue is empty; caller takes ownership of the metadata buffer inside
307     * the capture result object's metadata field.
308     * May be called concurrently to most methods, except for waitForNextFrame.
309     */
310    virtual status_t getNextResult(CaptureResult *frame) = 0;
311
312    /**
313     * Trigger auto-focus. The latest ID used in a trigger autofocus or cancel
314     * autofocus call will be returned by the HAL in all subsequent AF
315     * notifications.
316     */
317    virtual status_t triggerAutofocus(uint32_t id) = 0;
318
319    /**
320     * Cancel auto-focus. The latest ID used in a trigger autofocus/cancel
321     * autofocus call will be returned by the HAL in all subsequent AF
322     * notifications.
323     */
324    virtual status_t triggerCancelAutofocus(uint32_t id) = 0;
325
326    /**
327     * Trigger pre-capture metering. The latest ID used in a trigger pre-capture
328     * call will be returned by the HAL in all subsequent AE and AWB
329     * notifications.
330     */
331    virtual status_t triggerPrecaptureMetering(uint32_t id) = 0;
332
333    /**
334     * Flush all pending and in-flight requests. Blocks until flush is
335     * complete.
336     * Output lastFrameNumber is the last frame number of the previous streaming request.
337     */
338    virtual status_t flush(int64_t *lastFrameNumber = NULL) = 0;
339
340    /**
341     * Prepare stream by preallocating buffers for it asynchronously.
342     * Calls notifyPrepared() once allocation is complete.
343     */
344    virtual status_t prepare(int streamId) = 0;
345
346    /**
347     * Free stream resources by dumping its unused gralloc buffers.
348     */
349    virtual status_t tearDown(int streamId) = 0;
350
351    /**
352     * Add buffer listener for a particular stream in the device.
353     */
354    virtual status_t addBufferListenerForStream(int streamId,
355            wp<camera3::Camera3StreamBufferListener> listener) = 0;
356
357    /**
358     * Prepare stream by preallocating up to maxCount buffers for it asynchronously.
359     * Calls notifyPrepared() once allocation is complete.
360     */
361    virtual status_t prepare(int maxCount, int streamId) = 0;
362
363    /**
364     * Set the deferred consumer surface and finish the rest of the stream configuration.
365     */
366    virtual status_t setConsumerSurfaces(int streamId,
367            const std::vector<sp<Surface>>& consumers, std::vector<int> *surfaceIds /*out*/) = 0;
368
369    /**
370     * Update a given stream.
371     */
372    virtual status_t updateStream(int streamId, const std::vector<sp<Surface>> &newSurfaces,
373            const std::vector<android::camera3::OutputStreamInfo> &outputInfo,
374            const std::vector<size_t> &removedSurfaceIds,
375            KeyedVector<sp<Surface>, size_t> *outputMap/*out*/) = 0;
376
377    /**
378     * Drop buffers for stream of streamId if dropping is true. If dropping is false, do not
379     * drop buffers for stream of streamId.
380     */
381    virtual status_t dropStreamBuffers(bool /*dropping*/, int /*streamId*/) = 0;
382};
383
384}; // namespace android
385
386#endif
387