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