Camera3Device.h revision 7b82efe7a376c882f8f938e1c41b8311a8cdda4a 
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  private:
128    static const size_t        kInFlightWarnLimit = 20;
129    static const nsecs_t       kShutdownTimeout   = 5000000000; // 5 sec
130    struct                     RequestTrigger;
131
132    Mutex                      mLock;
133
134    /**** Scope for mLock ****/
135
136    const int                  mId;
137    camera3_device_t          *mHal3Device;
138
139    CameraMetadata             mDeviceInfo;
140    vendor_tag_query_ops_t     mVendorTagOps;
141
142    enum {
143        STATUS_ERROR,
144        STATUS_UNINITIALIZED,
145        STATUS_IDLE,
146        STATUS_ACTIVE
147    }                          mStatus;
148
149    // Tracking cause of fatal errors when in STATUS_ERROR
150    String8                    mErrorCause;
151
152    // Mapping of stream IDs to stream instances
153    typedef KeyedVector<int, sp<camera3::Camera3OutputStreamInterface> >
154            StreamSet;
155
156    StreamSet                  mOutputStreams;
157    sp<camera3::Camera3Stream> mInputStream;
158    int                        mNextStreamId;
159    bool                       mNeedConfig;
160
161    // Need to hold on to stream references until configure completes.
162    Vector<sp<camera3::Camera3StreamInterface> > mDeletedStreams;
163
164    /**** End scope for mLock ****/
165
166    class CaptureRequest : public LightRefBase<CaptureRequest> {
167      public:
168        CameraMetadata                      mSettings;
169        sp<camera3::Camera3Stream>          mInputStream;
170        Vector<sp<camera3::Camera3OutputStreamInterface> >
171                                            mOutputStreams;
172    };
173    typedef List<sp<CaptureRequest> > RequestList;
174
175    /**
176     * Lock-held version of waitUntilDrained. Will transition to IDLE on
177     * success.
178     */
179    status_t           waitUntilDrainedLocked();
180
181    /**
182     * Do common work for setting up a streaming or single capture request.
183     * On success, will transition to ACTIVE if in IDLE.
184     */
185    sp<CaptureRequest> setUpRequestLocked(const CameraMetadata &request);
186
187    /**
188     * Build a CaptureRequest request from the CameraDeviceBase request
189     * settings.
190     */
191    sp<CaptureRequest> createCaptureRequest(const CameraMetadata &request);
192
193    /**
194     * Take the currently-defined set of streams and configure the HAL to use
195     * them. This is a long-running operation (may be several hundered ms).
196     */
197    status_t           configureStreamsLocked();
198
199    /**
200     * Set device into an error state due to some fatal failure, and set an
201     * error message to indicate why. Only the first call's message will be
202     * used. The message is also sent to the log.
203     */
204    void               setErrorState(const char *fmt, ...);
205    void               setErrorStateV(const char *fmt, va_list args);
206    void               setErrorStateLocked(const char *fmt, ...);
207    void               setErrorStateLockedV(const char *fmt, va_list args);
208
209    struct RequestTrigger {
210        // Metadata tag number, e.g. android.control.aePrecaptureTrigger
211        uint32_t metadataTag;
212        // Metadata value, e.g. 'START' or the trigger ID
213        int32_t entryValue;
214
215        // The last part of the fully qualified path, e.g. afTrigger
216        const char *getTagName() const {
217            return get_camera_metadata_tag_name(metadataTag) ?: "NULL";
218        }
219
220        // e.g. TYPE_BYTE, TYPE_INT32, etc.
221        int getTagType() const {
222            return get_camera_metadata_tag_type(metadataTag);
223        }
224    };
225
226    /**
227     * Thread for managing capture request submission to HAL device.
228     */
229    class RequestThread : public Thread {
230
231      public:
232
233        RequestThread(wp<Camera3Device> parent,
234                camera3_device_t *hal3Device);
235
236        /**
237         * Call after stream (re)-configuration is completed.
238         */
239        void     configurationComplete();
240
241        /**
242         * Set or clear the list of repeating requests. Does not block
243         * on either. Use waitUntilPaused to wait until request queue
244         * has emptied out.
245         */
246        status_t setRepeatingRequests(const RequestList& requests);
247        status_t clearRepeatingRequests();
248
249        status_t queueRequest(sp<CaptureRequest> request);
250
251        /**
252         * Queue a trigger to be dispatched with the next outgoing
253         * process_capture_request. The settings for that request only
254         * will be temporarily rewritten to add the trigger tag/value.
255         * Subsequent requests will not be rewritten (for this tag).
256         */
257        status_t queueTrigger(RequestTrigger trigger[], size_t count);
258
259        /**
260         * Pause/unpause the capture thread. Doesn't block, so use
261         * waitUntilPaused to wait until the thread is paused.
262         */
263        void     setPaused(bool paused);
264
265        /**
266         * Wait until thread is paused, either due to setPaused(true)
267         * or due to lack of input requests. Returns TIMED_OUT in case
268         * the thread does not pause within the timeout.
269         */
270        status_t waitUntilPaused(nsecs_t timeout);
271
272        /**
273         * Wait until thread processes the capture request with settings'
274         * android.request.id == requestId.
275         *
276         * Returns TIMED_OUT in case the thread does not process the request
277         * within the timeout.
278         */
279        status_t waitUntilRequestProcessed(int32_t requestId, nsecs_t timeout);
280
281      protected:
282
283        virtual bool threadLoop();
284
285      private:
286        static int         getId(const wp<Camera3Device> &device);
287
288        status_t           queueTriggerLocked(RequestTrigger trigger);
289        // Mix-in queued triggers into this request
290        int32_t            insertTriggers(const sp<CaptureRequest> &request);
291        // Purge the queued triggers from this request,
292        //  restoring the old field values for those tags.
293        status_t           removeTriggers(const sp<CaptureRequest> &request);
294
295        static const nsecs_t kRequestTimeout = 50e6; // 50 ms
296
297        // Waits for a request, or returns NULL if times out.
298        sp<CaptureRequest> waitForNextRequest();
299
300        // Return buffers, etc, for a request that couldn't be fully
301        // constructed. The buffers will be returned in the ERROR state
302        // to mark them as not having valid data.
303        // All arguments will be modified.
304        void cleanUpFailedRequest(camera3_capture_request_t &request,
305                sp<CaptureRequest> &nextRequest,
306                Vector<camera3_stream_buffer_t> &outputBuffers);
307
308        // Pause handling
309        bool               waitIfPaused();
310
311        // Relay error to parent device object setErrorState
312        void               setErrorState(const char *fmt, ...);
313
314        wp<Camera3Device>  mParent;
315        camera3_device_t  *mHal3Device;
316
317        const int          mId;
318
319        Mutex              mRequestLock;
320        Condition          mRequestSignal;
321        RequestList        mRequestQueue;
322        RequestList        mRepeatingRequests;
323
324        bool               mReconfigured;
325
326        // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused
327        Mutex              mPauseLock;
328        bool               mDoPause;
329        Condition          mDoPauseSignal;
330        bool               mPaused;
331        Condition          mPausedSignal;
332
333        sp<CaptureRequest> mPrevRequest;
334        int32_t            mPrevTriggers;
335
336        uint32_t           mFrameNumber;
337
338        Mutex              mLatestRequestMutex;
339        Condition          mLatestRequestSignal;
340        // android.request.id for latest process_capture_request
341        int32_t            mLatestRequestId;
342
343        typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap;
344        Mutex              mTriggerMutex;
345        TriggerMap         mTriggerMap;
346        TriggerMap         mTriggerRemovedMap;
347        TriggerMap         mTriggerReplacedMap;
348    };
349    sp<RequestThread> mRequestThread;
350
351    /**
352     * In-flight queue for tracking completion of capture requests.
353     */
354
355    struct InFlightRequest {
356        // Set by notify() SHUTTER call.
357        nsecs_t captureTimestamp;
358        // Set by process_capture_result call with valid metadata
359        bool    haveResultMetadata;
360        // Decremented by calls to process_capture_result with valid output
361        // buffers
362        int     numBuffersLeft;
363
364        InFlightRequest() :
365                captureTimestamp(0),
366                haveResultMetadata(false),
367                numBuffersLeft(0) {
368        }
369
370        explicit InFlightRequest(int numBuffers) :
371                captureTimestamp(0),
372                haveResultMetadata(false),
373                numBuffersLeft(numBuffers) {
374        }
375    };
376    // Map from frame number to the in-flight request state
377    typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap;
378
379    Mutex                  mInFlightLock; // Protects mInFlightMap
380    InFlightMap            mInFlightMap;
381
382    status_t registerInFlight(int32_t frameNumber, int32_t numBuffers);
383
384    /**
385     * Output result queue and current HAL device 3A state
386     */
387
388    // Lock for output side of device
389    Mutex                  mOutputLock;
390
391    /**** Scope for mOutputLock ****/
392
393    uint32_t               mNextResultFrameNumber;
394    uint32_t               mNextShutterFrameNumber;
395    List<CameraMetadata>   mResultQueue;
396    Condition              mResultSignal;
397    NotificationListener  *mListener;
398
399    /**** End scope for mOutputLock ****/
400
401    /**
402     * Callback functions from HAL device
403     */
404    void processCaptureResult(const camera3_capture_result *result);
405
406    void notify(const camera3_notify_msg *msg);
407
408    /**
409     * Static callback forwarding methods from HAL to instance
410     */
411    static callbacks_process_capture_result_t sProcessCaptureResult;
412
413    static callbacks_notify_t sNotify;
414
415}; // class Camera3Device
416
417}; // namespace android
418
419#endif
420