Camera3Device.h revision abaa51d3ca31f0eda99e1d271e6dc64c877dbf58 
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_CAMERA3DEVICE_H
18#define ANDROID_SERVERS_CAMERA3DEVICE_H
19
20#include <utils/Condition.h>
21#include <utils/Errors.h>
22#include <utils/List.h>
23#include <utils/Mutex.h>
24#include <utils/Thread.h>
25#include <utils/KeyedVector.h>
26#include <hardware/camera3.h>
27
28#include "common/CameraDeviceBase.h"
29
30/**
31 * Function pointer types with C calling convention to
32 * use for HAL callback functions.
33 */
34extern "C" {
35    typedef void (callbacks_process_capture_result_t)(
36        const struct camera3_callback_ops *,
37        const camera3_capture_result_t *);
38
39    typedef void (callbacks_notify_t)(
40        const struct camera3_callback_ops *,
41        const camera3_notify_msg_t *);
42}
43
44namespace android {
45
46namespace camera3 {
47
48class Camera3Stream;
49class Camera3ZslStream;
50class Camera3OutputStreamInterface;
51class Camera3StreamInterface;
52
53}
54
55/**
56 * CameraDevice for HAL devices with version CAMERA_DEVICE_API_VERSION_3_0
57 */
58class Camera3Device :
59            public CameraDeviceBase,
60            private camera3_callback_ops {
61  public:
62    Camera3Device(int id);
63
64    virtual ~Camera3Device();
65
66    /**
67     * CameraDeviceBase interface
68     */
69
70    virtual int      getId() const;
71
72    // Transitions to idle state on success.
73    virtual status_t initialize(camera_module_t *module);
74    virtual status_t disconnect();
75    virtual status_t dump(int fd, const Vector<String16> &args);
76    virtual const CameraMetadata& info() const;
77
78    // Capture and setStreamingRequest will configure streams if currently in
79    // idle state
80    virtual status_t capture(CameraMetadata &request);
81    virtual status_t setStreamingRequest(const CameraMetadata &request);
82    virtual status_t clearStreamingRequest();
83
84    virtual status_t waitUntilRequestReceived(int32_t requestId, nsecs_t timeout);
85
86    // Actual stream creation/deletion is delayed until first request is submitted
87    // If adding streams while actively capturing, will pause device before adding
88    // stream, reconfiguring device, and unpausing.
89    virtual status_t createStream(sp<ANativeWindow> consumer,
90            uint32_t width, uint32_t height, int format, size_t size,
91            int *id);
92    virtual status_t createInputStream(
93            uint32_t width, uint32_t height, int format,
94            int *id);
95    virtual status_t createZslStream(
96            uint32_t width, uint32_t height,
97            int depth,
98            /*out*/
99            int *id,
100            sp<camera3::Camera3ZslStream>* zslStream);
101    virtual status_t createReprocessStreamFromStream(int outputId, int *id);
102
103    virtual status_t getStreamInfo(int id,
104            uint32_t *width, uint32_t *height, uint32_t *format);
105    virtual status_t setStreamTransform(int id, int transform);
106
107    virtual status_t deleteStream(int id);
108    virtual status_t deleteReprocessStream(int id);
109
110    virtual status_t createDefaultRequest(int templateId, CameraMetadata *request);
111
112    // Transitions to the idle state on success
113    virtual status_t waitUntilDrained();
114
115    virtual status_t setNotifyCallback(NotificationListener *listener);
116    virtual bool     willNotify3A();
117    virtual status_t waitForNextFrame(nsecs_t timeout);
118    virtual status_t getNextFrame(CameraMetadata *frame);
119
120    virtual status_t triggerAutofocus(uint32_t id);
121    virtual status_t triggerCancelAutofocus(uint32_t id);
122    virtual status_t triggerPrecaptureMetering(uint32_t id);
123
124    virtual status_t pushReprocessBuffer(int reprocessStreamId,
125            buffer_handle_t *buffer, wp<BufferReleasedListener> listener);
126
127    virtual status_t flush();
128
129  private:
130    static const size_t        kInFlightWarnLimit = 20;
131    static const nsecs_t       kShutdownTimeout   = 5000000000; // 5 sec
132    struct                     RequestTrigger;
133
134    Mutex                      mLock;
135
136    /**** Scope for mLock ****/
137
138    const int                  mId;
139    camera3_device_t          *mHal3Device;
140
141    CameraMetadata             mDeviceInfo;
142    vendor_tag_query_ops_t     mVendorTagOps;
143
144    enum {
145        STATUS_ERROR,
146        STATUS_UNINITIALIZED,
147        STATUS_IDLE,
148        STATUS_ACTIVE
149    }                          mStatus;
150
151    // Tracking cause of fatal errors when in STATUS_ERROR
152    String8                    mErrorCause;
153
154    // Mapping of stream IDs to stream instances
155    typedef KeyedVector<int, sp<camera3::Camera3OutputStreamInterface> >
156            StreamSet;
157
158    StreamSet                  mOutputStreams;
159    sp<camera3::Camera3Stream> mInputStream;
160    int                        mNextStreamId;
161    bool                       mNeedConfig;
162
163    // Need to hold on to stream references until configure completes.
164    Vector<sp<camera3::Camera3StreamInterface> > mDeletedStreams;
165
166    /**** End scope for mLock ****/
167
168    class CaptureRequest : public LightRefBase<CaptureRequest> {
169      public:
170        CameraMetadata                      mSettings;
171        sp<camera3::Camera3Stream>          mInputStream;
172        Vector<sp<camera3::Camera3OutputStreamInterface> >
173                                            mOutputStreams;
174    };
175    typedef List<sp<CaptureRequest> > RequestList;
176
177    /**
178     * Lock-held version of waitUntilDrained. Will transition to IDLE on
179     * success.
180     */
181    status_t           waitUntilDrainedLocked();
182
183    /**
184     * Do common work for setting up a streaming or single capture request.
185     * On success, will transition to ACTIVE if in IDLE.
186     */
187    sp<CaptureRequest> setUpRequestLocked(const CameraMetadata &request);
188
189    /**
190     * Build a CaptureRequest request from the CameraDeviceBase request
191     * settings.
192     */
193    sp<CaptureRequest> createCaptureRequest(const CameraMetadata &request);
194
195    /**
196     * Take the currently-defined set of streams and configure the HAL to use
197     * them. This is a long-running operation (may be several hundered ms).
198     */
199    status_t           configureStreamsLocked();
200
201    /**
202     * Set device into an error state due to some fatal failure, and set an
203     * error message to indicate why. Only the first call's message will be
204     * used. The message is also sent to the log.
205     */
206    void               setErrorState(const char *fmt, ...);
207    void               setErrorStateV(const char *fmt, va_list args);
208    void               setErrorStateLocked(const char *fmt, ...);
209    void               setErrorStateLockedV(const char *fmt, va_list args);
210
211    struct RequestTrigger {
212        // Metadata tag number, e.g. android.control.aePrecaptureTrigger
213        uint32_t metadataTag;
214        // Metadata value, e.g. 'START' or the trigger ID
215        int32_t entryValue;
216
217        // The last part of the fully qualified path, e.g. afTrigger
218        const char *getTagName() const {
219            return get_camera_metadata_tag_name(metadataTag) ?: "NULL";
220        }
221
222        // e.g. TYPE_BYTE, TYPE_INT32, etc.
223        int getTagType() const {
224            return get_camera_metadata_tag_type(metadataTag);
225        }
226    };
227
228    /**
229     * Thread for managing capture request submission to HAL device.
230     */
231    class RequestThread : public Thread {
232
233      public:
234
235        RequestThread(wp<Camera3Device> parent,
236                camera3_device_t *hal3Device);
237
238        /**
239         * Call after stream (re)-configuration is completed.
240         */
241        void     configurationComplete();
242
243        /**
244         * Set or clear the list of repeating requests. Does not block
245         * on either. Use waitUntilPaused to wait until request queue
246         * has emptied out.
247         */
248        status_t setRepeatingRequests(const RequestList& requests);
249        status_t clearRepeatingRequests();
250
251        status_t queueRequest(sp<CaptureRequest> request);
252
253        /**
254         * Remove all queued and repeating requests, and pending triggers
255         */
256        status_t clear();
257
258        /**
259         * Queue a trigger to be dispatched with the next outgoing
260         * process_capture_request. The settings for that request only
261         * will be temporarily rewritten to add the trigger tag/value.
262         * Subsequent requests will not be rewritten (for this tag).
263         */
264        status_t queueTrigger(RequestTrigger trigger[], size_t count);
265
266        /**
267         * Pause/unpause the capture thread. Doesn't block, so use
268         * waitUntilPaused to wait until the thread is paused.
269         */
270        void     setPaused(bool paused);
271
272        /**
273         * Wait until thread is paused, either due to setPaused(true)
274         * or due to lack of input requests. Returns TIMED_OUT in case
275         * the thread does not pause within the timeout.
276         */
277        status_t waitUntilPaused(nsecs_t timeout);
278
279        /**
280         * Wait until thread processes the capture request with settings'
281         * android.request.id == requestId.
282         *
283         * Returns TIMED_OUT in case the thread does not process the request
284         * within the timeout.
285         */
286        status_t waitUntilRequestProcessed(int32_t requestId, nsecs_t timeout);
287
288      protected:
289
290        virtual bool threadLoop();
291
292      private:
293        static int         getId(const wp<Camera3Device> &device);
294
295        status_t           queueTriggerLocked(RequestTrigger trigger);
296        // Mix-in queued triggers into this request
297        int32_t            insertTriggers(const sp<CaptureRequest> &request);
298        // Purge the queued triggers from this request,
299        //  restoring the old field values for those tags.
300        status_t           removeTriggers(const sp<CaptureRequest> &request);
301
302        static const nsecs_t kRequestTimeout = 50e6; // 50 ms
303
304        // Waits for a request, or returns NULL if times out.
305        sp<CaptureRequest> waitForNextRequest();
306
307        // Return buffers, etc, for a request that couldn't be fully
308        // constructed. The buffers will be returned in the ERROR state
309        // to mark them as not having valid data.
310        // All arguments will be modified.
311        void cleanUpFailedRequest(camera3_capture_request_t &request,
312                sp<CaptureRequest> &nextRequest,
313                Vector<camera3_stream_buffer_t> &outputBuffers);
314
315        // Pause handling
316        bool               waitIfPaused();
317
318        // Relay error to parent device object setErrorState
319        void               setErrorState(const char *fmt, ...);
320
321        wp<Camera3Device>  mParent;
322        camera3_device_t  *mHal3Device;
323
324        const int          mId;
325
326        Mutex              mRequestLock;
327        Condition          mRequestSignal;
328        RequestList        mRequestQueue;
329        RequestList        mRepeatingRequests;
330
331        bool               mReconfigured;
332
333        // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused
334        Mutex              mPauseLock;
335        bool               mDoPause;
336        Condition          mDoPauseSignal;
337        bool               mPaused;
338        Condition          mPausedSignal;
339
340        sp<CaptureRequest> mPrevRequest;
341        int32_t            mPrevTriggers;
342
343        uint32_t           mFrameNumber;
344
345        Mutex              mLatestRequestMutex;
346        Condition          mLatestRequestSignal;
347        // android.request.id for latest process_capture_request
348        int32_t            mLatestRequestId;
349
350        typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap;
351        Mutex              mTriggerMutex;
352        TriggerMap         mTriggerMap;
353        TriggerMap         mTriggerRemovedMap;
354        TriggerMap         mTriggerReplacedMap;
355    };
356    sp<RequestThread> mRequestThread;
357
358    /**
359     * In-flight queue for tracking completion of capture requests.
360     */
361
362    struct InFlightRequest {
363        // Set by notify() SHUTTER call.
364        nsecs_t captureTimestamp;
365        // Set by process_capture_result call with valid metadata
366        bool    haveResultMetadata;
367        // Decremented by calls to process_capture_result with valid output
368        // buffers
369        int     numBuffersLeft;
370
371        InFlightRequest() :
372                captureTimestamp(0),
373                haveResultMetadata(false),
374                numBuffersLeft(0) {
375        }
376
377        explicit InFlightRequest(int numBuffers) :
378                captureTimestamp(0),
379                haveResultMetadata(false),
380                numBuffersLeft(numBuffers) {
381        }
382    };
383    // Map from frame number to the in-flight request state
384    typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap;
385
386    Mutex                  mInFlightLock; // Protects mInFlightMap
387    InFlightMap            mInFlightMap;
388
389    status_t registerInFlight(int32_t frameNumber, int32_t numBuffers);
390
391    /**
392     * Output result queue and current HAL device 3A state
393     */
394
395    // Lock for output side of device
396    Mutex                  mOutputLock;
397
398    /**** Scope for mOutputLock ****/
399
400    uint32_t               mNextResultFrameNumber;
401    uint32_t               mNextShutterFrameNumber;
402    List<CameraMetadata>   mResultQueue;
403    Condition              mResultSignal;
404    NotificationListener  *mListener;
405
406    /**** End scope for mOutputLock ****/
407
408    /**
409     * Callback functions from HAL device
410     */
411    void processCaptureResult(const camera3_capture_result *result);
412
413    void notify(const camera3_notify_msg *msg);
414
415    /**
416     * Static callback forwarding methods from HAL to instance
417     */
418    static callbacks_process_capture_result_t sProcessCaptureResult;
419
420    static callbacks_notify_t sNotify;
421
422}; // class Camera3Device
423
424}; // namespace android
425
426#endif
427