2 * Copyright (C) 2012 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * This class is a simple simulation of a typical CMOS cellphone imager chip,
19 * which outputs 12-bit Bayer-mosaic raw images.
21 * Unlike most real image sensors, this one's native color space is linear sRGB.
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
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.
39 * The characteristics of this sensor don't correspond to any actual sensor,
40 * but are not far off typical sensors.
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.
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_______\
75 #ifndef HW_EMULATOR_CAMERA2_SENSOR_H
76 #define HW_EMULATOR_CAMERA2_SENSOR_H
78 #include "utils/Thread.h"
79 #include "utils/Mutex.h"
80 #include "utils/Timers.h"
87 class EmulatedFakeCamera2;
89 class Sensor: private Thread, public virtual RefBase {
108 * Controls that can be updated every frame
111 void setExposureTime(uint64_t ns);
112 void setFrameDuration(uint64_t ns);
113 void setSensitivity(uint32_t gain);
114 // Buffer must be at least stride*height*2 bytes in size
115 void setDestinationBuffers(Buffers *buffers);
116 // To simplify tracking sensor's current frame
117 void setFrameNumber(uint32_t frameNumber);
120 * Controls that cause reconfiguration delay
123 void setBinning(int horizontalFactor, int verticalFactor);
126 * Synchronizing with sensor operation (vertical sync)
129 // Wait until the sensor outputs its next vertical sync signal, meaning it
130 // is starting readout of its latest frame of data. Returns true if vertical
131 // sync is signaled, false if the wait timed out.
132 bool waitForVSync(nsecs_t reltime);
134 // Wait until a new frame has been read out, and then return the time
135 // capture started. May return immediately if a new frame has been pushed
136 // since the last wait for a new frame. Returns true if new frame is
137 // returned, false if timed out.
138 bool waitForNewFrame(nsecs_t reltime,
139 nsecs_t *captureTime);
142 * Interrupt event servicing from the sensor. Only triggers for sensor
143 * cycles that have valid buffers to write to.
145 struct SensorListener {
147 EXPOSURE_START, // Start of exposure
150 virtual void onSensorEvent(uint32_t frameNumber, Event e,
151 nsecs_t timestamp) = 0;
152 virtual ~SensorListener();
155 void setSensorListener(SensorListener *listener);
158 * Static sensor characteristics
160 static const unsigned int kResolution[2];
161 static const unsigned int kActiveArray[4];
163 static const nsecs_t kExposureTimeRange[2];
164 static const nsecs_t kFrameDurationRange[2];
165 static const nsecs_t kMinVerticalBlank;
167 static const uint8_t kColorFilterArrangement;
169 // Output image data characteristics
170 static const uint32_t kMaxRawValue;
171 static const uint32_t kBlackLevel;
172 // Sensor sensitivity, approximate
174 static const float kSaturationVoltage;
175 static const uint32_t kSaturationElectrons;
176 static const float kVoltsPerLuxSecond;
177 static const float kElectronsPerLuxSecond;
179 static const float kBaseGainFactor;
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;
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 static const nsecs_t kRowReadoutTime;
192 static const int32_t kSensitivityRange[2];
193 static const uint32_t kDefaultSensitivity;
196 Mutex mControlMutex; // Lock before accessing control parameters
197 // Start of control parameters
200 uint64_t mExposureTime;
201 uint64_t mFrameDuration;
202 uint32_t mGainFactor;
203 Buffers *mNextBuffers;
204 uint32_t mFrameNumber;
206 // End of control parameters
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
217 // Time of sensor startup, used for simulation zero-time point
218 nsecs_t mStartupTime;
221 * Inherited Thread virtual overrides, and members only used by the
225 virtual status_t readyToRun();
227 virtual bool threadLoop();
229 nsecs_t mNextCaptureTime;
230 Buffers *mNextCapturedBuffers;
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);
245 #endif // HW_EMULATOR_CAMERA2_SENSOR_H