1/*
2 * Copyright (C) 2012 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/**
18 * This class is a simple simulation of a typical CMOS cellphone imager chip,
19 * which outputs 12-bit Bayer-mosaic raw images.
20 *
21 * The sensor is abstracted as operating as a pipeline 3 stages deep;
22 * conceptually, each frame to be captured goes through these three stages. The
23 * processing step for the sensor is marked off by vertical sync signals, which
24 * indicate the start of readout of the oldest frame. The interval between
25 * processing steps depends on the frame duration of the frame currently being
26 * captured. The stages are 1) configure, 2) capture, and 3) readout. During
27 * configuration, the sensor's registers for settings such as exposure time,
28 * frame duration, and gain are set for the next frame to be captured. In stage
29 * 2, the image data for the frame is actually captured by the sensor. Finally,
30 * in stage 3, the just-captured data is read out and sent to the rest of the
31 * system.
32 *
33 * The sensor is assumed to be rolling-shutter, so low-numbered rows of the
34 * sensor are exposed earlier in time than larger-numbered rows, with the time
35 * offset between each row being equal to the row readout time.
36 *
37 * The characteristics of this sensor don't correspond to any actual sensor,
38 * but are not far off typical sensors.
39 *
40 * Example timing diagram, with three frames:
41 *  Frame 0-1: Frame duration 50 ms, exposure time 20 ms.
42 *  Frame   2: Frame duration 75 ms, exposure time 65 ms.
43 * Legend:
44 *   C = update sensor registers for frame
45 *   v = row in reset (vertical blanking interval)
46 *   E = row capturing image data
47 *   R = row being read out
48 *   | = vertical sync signal
49 *time(ms)|   0          55        105       155            230     270
50 * Frame 0|   :configure : capture : readout :              :       :
51 *  Row # | ..|CCCC______|_________|_________|              :       :
52 *      0 |   :\          \vvvvvEEEER         \             :       :
53 *    500 |   : \          \vvvvvEEEER         \            :       :
54 *   1000 |   :  \          \vvvvvEEEER         \           :       :
55 *   1500 |   :   \          \vvvvvEEEER         \          :       :
56 *   2000 |   :    \__________\vvvvvEEEER_________\         :       :
57 * Frame 1|   :           configure  capture      readout   :       :
58 *  Row # |   :          |CCCC_____|_________|______________|       :
59 *      0 |   :          :\         \vvvvvEEEER              \      :
60 *    500 |   :          : \         \vvvvvEEEER              \     :
61 *   1000 |   :          :  \         \vvvvvEEEER              \    :
62 *   1500 |   :          :   \         \vvvvvEEEER              \   :
63 *   2000 |   :          :    \_________\vvvvvEEEER______________\  :
64 * Frame 2|   :          :          configure     capture    readout:
65 *  Row # |   :          :         |CCCC_____|______________|_______|...
66 *      0 |   :          :         :\         \vEEEEEEEEEEEEER       \
67 *    500 |   :          :         : \         \vEEEEEEEEEEEEER       \
68 *   1000 |   :          :         :  \         \vEEEEEEEEEEEEER       \
69 *   1500 |   :          :         :   \         \vEEEEEEEEEEEEER       \
70 *   2000 |   :          :         :    \_________\vEEEEEEEEEEEEER_______\
71 */
72
73#ifndef HW_EMULATOR_CAMERA2_SENSOR_H
74#define HW_EMULATOR_CAMERA2_SENSOR_H
75
76#include "utils/Thread.h"
77#include "utils/Mutex.h"
78#include "utils/Timers.h"
79
80#include "Scene.h"
81#include "Base.h"
82
83namespace android {
84
85class EmulatedFakeCamera2;
86
87class Sensor: private Thread, public virtual RefBase {
88  public:
89
90    Sensor(EmulatedFakeCamera2 *parent);
91    ~Sensor();
92
93    /*
94     * Power control
95     */
96
97    status_t startUp();
98    status_t shutDown();
99
100    /*
101     * Access to scene
102     */
103    Scene &getScene();
104
105    /*
106     * Controls that can be updated every frame
107     */
108
109    void setExposureTime(uint64_t ns);
110    void setFrameDuration(uint64_t ns);
111    void setSensitivity(uint32_t gain);
112    // Buffer must be at least stride*height*2 bytes in size
113    void setDestinationBuffers(Buffers *buffers);
114
115    /*
116     * Controls that cause reconfiguration delay
117     */
118
119    void setBinning(int horizontalFactor, int verticalFactor);
120
121    /*
122     * Synchronizing with sensor operation (vertical sync)
123     */
124
125    // Wait until the sensor outputs its next vertical sync signal, meaning it
126    // is starting readout of its latest frame of data. Returns true if vertical
127    // sync is signaled, false if the wait timed out.
128    bool waitForVSync(nsecs_t reltime);
129
130    // Wait until a new frame has been read out, and then return the time
131    // capture started.  May return immediately if a new frame has been pushed
132    // since the last wait for a new frame. Returns true if new frame is
133    // returned, false if timed out.
134    bool waitForNewFrame(nsecs_t reltime,
135            nsecs_t *captureTime);
136
137    /**
138     * Static sensor characteristics
139     */
140    static const unsigned int kResolution[2];
141
142    static const nsecs_t kExposureTimeRange[2];
143    static const nsecs_t kFrameDurationRange[2];
144    static const nsecs_t kMinVerticalBlank;
145
146    static const uint8_t kColorFilterArrangement;
147
148    // Output image data characteristics
149    static const uint32_t kMaxRawValue;
150    static const uint32_t kBlackLevel;
151    // Sensor sensitivity, approximate
152
153    static const float kSaturationVoltage;
154    static const uint32_t kSaturationElectrons;
155    static const float kVoltsPerLuxSecond;
156    static const float kElectronsPerLuxSecond;
157
158    static const float kBaseGainFactor;
159
160    static const float kReadNoiseStddevBeforeGain; // In electrons
161    static const float kReadNoiseStddevAfterGain;  // In raw digital units
162    static const float kReadNoiseVarBeforeGain;
163    static const float kReadNoiseVarAfterGain;
164
165    // While each row has to read out, reset, and then expose, the (reset +
166    // expose) sequence can be overlapped by other row readouts, so the final
167    // minimum frame duration is purely a function of row readout time, at least
168    // if there's a reasonable number of rows.
169    static const nsecs_t kRowReadoutTime;
170
171    static const uint32_t kAvailableSensitivities[5];
172    static const uint32_t kDefaultSensitivity;
173
174  private:
175    EmulatedFakeCamera2 *mParent;
176
177    Mutex mControlMutex; // Lock before accessing control parameters
178    // Start of control parameters
179    Condition mVSync;
180    bool      mGotVSync;
181    uint64_t  mExposureTime;
182    uint64_t  mFrameDuration;
183    uint32_t  mGainFactor;
184    Buffers  *mNextBuffers;
185
186    // End of control parameters
187
188    Mutex mReadoutMutex; // Lock before accessing readout variables
189    // Start of readout variables
190    Condition mReadoutAvailable;
191    Condition mReadoutComplete;
192    Buffers  *mCapturedBuffers;
193    nsecs_t   mCaptureTime;
194    // End of readout variables
195
196    // Time of sensor startup, used for simulation zero-time point
197    nsecs_t mStartupTime;
198
199    /**
200     * Inherited Thread virtual overrides, and members only used by the
201     * processing thread
202     */
203  private:
204    virtual status_t readyToRun();
205
206    virtual bool threadLoop();
207
208    nsecs_t mNextCaptureTime;
209    Buffers *mNextCapturedBuffers;
210
211    Scene mScene;
212
213    void captureRaw(uint8_t *img, uint32_t gain, uint32_t stride);
214    void captureRGBA(uint8_t *img, uint32_t gain, uint32_t stride);
215    void captureRGB(uint8_t *img, uint32_t gain, uint32_t stride);
216    void captureNV21(uint8_t *img, uint32_t gain, uint32_t stride);
217};
218
219}
220
221#endif // HW_EMULATOR_CAMERA2_SENSOR_H
222