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(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