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