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 
38 namespace android {
39 
40 class CameraProviderManager;
41 
42 // Mapping of output stream index to surface ids
43 typedef 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  */
49 class 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 
StreamInfoStreamInfo173         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          */
matchFormatStreamInfo180         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          */
matchDataSpaceStreamInfo192         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