Camera3Device.h revision 26fe6c7c56477ef227205c68f17df07ca3501d65 
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        void               unpauseForNewRequests();
318
319        // Relay error to parent device object setErrorState
320        void               setErrorState(const char *fmt, ...);
321
322        wp<Camera3Device>  mParent;
323        camera3_device_t  *mHal3Device;
324
325        const int          mId;
326
327        Mutex              mRequestLock;
328        Condition          mRequestSignal;
329        RequestList        mRequestQueue;
330        RequestList        mRepeatingRequests;
331
332        bool               mReconfigured;
333
334        // Used by waitIfPaused, waitForNextRequest, and waitUntilPaused
335        Mutex              mPauseLock;
336        bool               mDoPause;
337        Condition          mDoPauseSignal;
338        bool               mPaused;
339        Condition          mPausedSignal;
340
341        sp<CaptureRequest> mPrevRequest;
342        int32_t            mPrevTriggers;
343
344        uint32_t           mFrameNumber;
345
346        Mutex              mLatestRequestMutex;
347        Condition          mLatestRequestSignal;
348        // android.request.id for latest process_capture_request
349        int32_t            mLatestRequestId;
350
351        typedef KeyedVector<uint32_t/*tag*/, RequestTrigger> TriggerMap;
352        Mutex              mTriggerMutex;
353        TriggerMap         mTriggerMap;
354        TriggerMap         mTriggerRemovedMap;
355        TriggerMap         mTriggerReplacedMap;
356    };
357    sp<RequestThread> mRequestThread;
358
359    /**
360     * In-flight queue for tracking completion of capture requests.
361     */
362
363    struct InFlightRequest {
364        // Set by notify() SHUTTER call.
365        nsecs_t captureTimestamp;
366        // Set by process_capture_result call with valid metadata
367        bool    haveResultMetadata;
368        // Decremented by calls to process_capture_result with valid output
369        // buffers
370        int     numBuffersLeft;
371
372        InFlightRequest() :
373                captureTimestamp(0),
374                haveResultMetadata(false),
375                numBuffersLeft(0) {
376        }
377
378        explicit InFlightRequest(int numBuffers) :
379                captureTimestamp(0),
380                haveResultMetadata(false),
381                numBuffersLeft(numBuffers) {
382        }
383    };
384    // Map from frame number to the in-flight request state
385    typedef KeyedVector<uint32_t, InFlightRequest> InFlightMap;
386
387    Mutex                  mInFlightLock; // Protects mInFlightMap
388    InFlightMap            mInFlightMap;
389
390    status_t registerInFlight(int32_t frameNumber, int32_t numBuffers);
391
392    /**
393     * Output result queue and current HAL device 3A state
394     */
395
396    // Lock for output side of device
397    Mutex                  mOutputLock;
398
399    /**** Scope for mOutputLock ****/
400
401    uint32_t               mNextResultFrameNumber;
402    uint32_t               mNextShutterFrameNumber;
403    List<CameraMetadata>   mResultQueue;
404    Condition              mResultSignal;
405    NotificationListener  *mListener;
406
407    /**** End scope for mOutputLock ****/
408
409    /**
410     * Callback functions from HAL device
411     */
412    void processCaptureResult(const camera3_capture_result *result);
413
414    void notify(const camera3_notify_msg *msg);
415
416    /**
417     * Static callback forwarding methods from HAL to instance
418     */
419    static callbacks_process_capture_result_t sProcessCaptureResult;
420
421    static callbacks_notify_t sNotify;
422
423}; // class Camera3Device
424
425}; // namespace android
426
427#endif
428