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 83 namespace android { 84 85 class EmulatedFakeCamera2; 86 87 class Sensor: private Thread, public virtual RefBase { 88 public: 89 90 Sensor(); 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 // To simplify tracking sensor's current frame 115 void setFrameNumber(uint32_t frameNumber); 116 117 /* 118 * Controls that cause reconfiguration delay 119 */ 120 121 void setBinning(int horizontalFactor, int verticalFactor); 122 123 /* 124 * Synchronizing with sensor operation (vertical sync) 125 */ 126 127 // Wait until the sensor outputs its next vertical sync signal, meaning it 128 // is starting readout of its latest frame of data. Returns true if vertical 129 // sync is signaled, false if the wait timed out. 130 bool waitForVSync(nsecs_t reltime); 131 132 // Wait until a new frame has been read out, and then return the time 133 // capture started. May return immediately if a new frame has been pushed 134 // since the last wait for a new frame. Returns true if new frame is 135 // returned, false if timed out. 136 bool waitForNewFrame(nsecs_t reltime, 137 nsecs_t *captureTime); 138 139 /* 140 * Interrupt event servicing from the sensor. Only triggers for sensor 141 * cycles that have valid buffers to write to. 142 */ 143 struct SensorListener { 144 enum Event { 145 EXPOSURE_START, // Start of exposure 146 }; 147 148 virtual void onSensorEvent(uint32_t frameNumber, Event e, 149 nsecs_t timestamp) = 0; 150 virtual ~SensorListener(); 151 }; 152 153 void setSensorListener(SensorListener *listener); 154 155 /** 156 * Static sensor characteristics 157 */ 158 static const unsigned int kResolution[2]; 159 160 static const nsecs_t kExposureTimeRange[2]; 161 static const nsecs_t kFrameDurationRange[2]; 162 static const nsecs_t kMinVerticalBlank; 163 164 static const uint8_t kColorFilterArrangement; 165 166 // Output image data characteristics 167 static const uint32_t kMaxRawValue; 168 static const uint32_t kBlackLevel; 169 // Sensor sensitivity, approximate 170 171 static const float kSaturationVoltage; 172 static const uint32_t kSaturationElectrons; 173 static const float kVoltsPerLuxSecond; 174 static const float kElectronsPerLuxSecond; 175 176 static const float kBaseGainFactor; 177 178 static const float kReadNoiseStddevBeforeGain; // In electrons 179 static const float kReadNoiseStddevAfterGain; // In raw digital units 180 static const float kReadNoiseVarBeforeGain; 181 static const float kReadNoiseVarAfterGain; 182 183 // While each row has to read out, reset, and then expose, the (reset + 184 // expose) sequence can be overlapped by other row readouts, so the final 185 // minimum frame duration is purely a function of row readout time, at least 186 // if there's a reasonable number of rows. 187 static const nsecs_t kRowReadoutTime; 188 189 static const uint32_t kAvailableSensitivities[5]; 190 static const uint32_t kDefaultSensitivity; 191 192 private: 193 Mutex mControlMutex; // Lock before accessing control parameters 194 // Start of control parameters 195 Condition mVSync; 196 bool mGotVSync; 197 uint64_t mExposureTime; 198 uint64_t mFrameDuration; 199 uint32_t mGainFactor; 200 Buffers *mNextBuffers; 201 uint32_t mFrameNumber; 202 203 // End of control parameters 204 205 Mutex mReadoutMutex; // Lock before accessing readout variables 206 // Start of readout variables 207 Condition mReadoutAvailable; 208 Condition mReadoutComplete; 209 Buffers *mCapturedBuffers; 210 nsecs_t mCaptureTime; 211 SensorListener *mListener; 212 // End of readout variables 213 214 // Time of sensor startup, used for simulation zero-time point 215 nsecs_t mStartupTime; 216 217 /** 218 * Inherited Thread virtual overrides, and members only used by the 219 * processing thread 220 */ 221 private: 222 virtual status_t readyToRun(); 223 224 virtual bool threadLoop(); 225 226 nsecs_t mNextCaptureTime; 227 Buffers *mNextCapturedBuffers; 228 229 Scene mScene; 230 231 void captureRaw(uint8_t *img, uint32_t gain, uint32_t stride); 232 void captureRGBA(uint8_t *img, uint32_t gain, uint32_t stride); 233 void captureRGB(uint8_t *img, uint32_t gain, uint32_t stride); 234 void captureNV21(uint8_t *img, uint32_t gain, uint32_t stride); 235 }; 236 237 } 238 239 #endif // HW_EMULATOR_CAMERA2_SENSOR_H 240
