Sensor Library Data Structure

The Sensor Library defines one top-level object (ST_SENSOR) and four subordinate structures that are returned by its function pointers:
ST_SENSOR  (top-level sensor object)
  │
  ├─ GetStatus() ────────→ SENSOR_STATUS
  ├─ GetMode() ───────────→ SENSOR_MODE
  ├─ GetInterfaceInfo() ──→ SENSOR_INTFC
  └─ GetInfo() ───────────→ SENSOR_INFO
                              ├─ .stStatus ──→ SENSOR_STATUS
                              └─ .stMode ────→ SENSOR_MODE
SENSOR_INFO nests SENSOR_STATUS and SENSOR_MODE as members, providing a snapshot of the sensor's current state and mode configuration in a single call.

ST_SENSOR

The top-level sensor object. It holds sensor state variables and function pointers that the ISP SDK calls to interact with the sensor hardware. The following is the definition of the sensor object.

typedef struct _ST_SENSOR {
    SENSOR_HANDLE *pstSensorHandle;
    EN_SENSOR_STATE enState;
    STF_U6 u6Width;
    STF_U6 u6Height;
    STF_U8 u8Imager;
    STF_U6 u6VerticalTotal;
    enum MOSAICType enBayerFormat;
    STF_U8 u8SensorContexts;
    STF_U8 u8BitDepth;
    STF_DOUBLE dFrameRate;
    STF_DOUBLE dCurrentFPS;
    STF_U32 u32WellDepth;
    STF_DOUBLE dReadNoise;
    STF_DOUBLE dAperture;
    STF_U6 u6FocalLength;
    STF_U32 u32ProgrammedExposure;
    STF_DOUBLE dProgrammedGain;
    STF_U6 u6ProgrammedFocus;
    STF_U32 u32MinExposure;
    STF_U32 u32MaxExposure;
    STF_U6 u6MinFocus;
    STF_U6 u6MaxFocus;
    STF_DOUBLE dMinGain;
    STF_DOUBLE dMaxGain;
    STF_BOOL8 bFocusSupported;

    const STF_CHAR* (*StateName)(EN_SENSOR_STATE enState);
    STF_VOID (*GetSensorNames)(STF_U8 *pu8Count, STF_CHAR szSensorName[][64]);
    STF_S8 (*GetSensorId)(const char *SensorName);

    STF_RESULT (*Init)(ST_SENSOR *pstSensor, STF_U8 u8SensorId, STF_U8 u8Index);
    STF_RESULT (*Destroy)(ST_SENSOR *pstSensor);
    SENSOR_HANDLE *(*GetHandle)(ST_SENSOR *pstSensor);
    EN_SENSOR_STATE (*GetState)(ST_SENSOR *pstSensor);
    STF_RESULT (*GetInfo)(ST_SENSOR *pstSensor, SENSOR_INFO *pstSensorInfo);
    STF_S8 (*GetModeIdx)(ST_SENSOR *pstSensor, STF_U6 u6Width, STF_U6 u6Height);
    STF_RESULT (*GetMode)(ST_SENSOR *pstSensor, STF_U8 u8ModeIdx, SENSOR_MODE *pstModes);
    STF_RESULT (*SetMode)(ST_SENSOR *pstSensor, STF_U8 u8ModeIdx, STF_U8 u8Flipping);
    STF_RESULT (*GetInterfaceInfo)(ST_SENSOR *pstSensor, SENSOR_INTFC *pstInterface);
    STF_RESULT (*Configure)(ST_SENSOR *pstSensor, STF_U8 u8ModeIdx, STF_U8 u8Flipping);
    STF_RESULT (*Insert)(ST_SENSOR *pstSensor);
    STF_RESULT (*WaitProcessed)(ST_SENSOR *pstSensor);
    STF_RESULT (*Enable)(ST_SENSOR *pstSensor);
    STF_RESULT (*Disable)(ST_SENSOR *pstSensor);
    STF_RESULT (*Reset)(ST_SENSOR *pstSensor);
    STF_RESULT (*GetStatus)(ST_SENSOR *pstSensor, SENSOR_STATUS *pstStatus);
    STF_RESULT (*GetReg)(ST_SENSOR *pstSensor, STF_U6 u6RegAddr, STF_U6 *pu6RegValue);
    STF_RESULT (*SetReg)(ST_SENSOR *pstSensor, STF_U6 u6RegAddr, STF_U6 u6RegValue);
    STF_RESULT (*SetFlipMirror)(ST_SENSOR *pstSensor, STF_U8 u8Flag);
    STF_RESULT (*GetFixedFPS)(ST_SENSOR *pstSensor, STF_U6 *pu6FixedFps);
    STF_RESULT (*SetFPS)(ST_SENSOR *pstSensor, STF_DOUBLE dFps);
    STF_RESULT (*GetSnapShotResolution)(ST_SENSOR *pstSensor, ST_RES_LIST *pstResList);
    STF_RESULT (*SetResolution)(ST_SENSOR *pstSensor, STF_U6 u6ImgW, STF_U6 u6ImgH);
    STF_U32 (*GetMinExposure)(ST_SENSOR *pstSensor);
    STF_U32 (*GetMaxExposure)(ST_SENSOR *pstSensor);
    STF_RESULT (*GetExposureRange)(ST_SENSOR *pstSensor, STF_U32 *pu32MinExposure, STF_U32 *pu32MaxExposure);
    STF_U32 (*GetExposure)(ST_SENSOR *pstSensor);
    STF_RESULT (*SetExposure)(ST_SENSOR *pstSensor, STF_U32 u32Exposure);
    STF_DOUBLE (*GetMinGain)(ST_SENSOR *pstSensor);
    STF_RESULT (*SetMinGain)(ST_SENSOR *pstSensor, STF_DOUBLE dMinGain);
    STF_DOUBLE (*GetMaxGain)(ST_SENSOR *pstSensor);
    STF_RESULT (*SetMaxGain)(ST_SENSOR *pstSensor, STF_DOUBLE dMaxGain);
    STF_RESULT (*GetGainRange)(ST_SENSOR *pstSensor, STF_DOUBLE *pdMinGain, STF_DOUBLE *pdMaxGain);
    STF_RESULT (*SetIsoLimit)(ST_SENSOR *pstSensor, STF_U8 u8IsoLimit);
    STF_DOUBLE (*GetGain)(ST_SENSOR *pstSensor);
    STF_RESULT (*SetGain)(ST_SENSOR *pstSensor, STF_DOUBLE dGain);
    STF_RESULT (*SetExposureAndGain)(ST_SENSOR *pstSensor, STF_U32 u32Exposure, STF_DOUBLE dGain);
    STF_BOOL8 (*GetFocusSupported)(ST_SENSOR *pstSensor);
    STF_U6 (*GetMinFocus)(ST_SENSOR *pstSensor);
    STF_U6 (*GetMaxFocus)(ST_SENSOR *pstSensor);
    STF_U6 (*GetFocusDistance)(ST_SENSOR *pstSensor);
    STF_RESULT (*SetFocusDistance)(ST_SENSOR *pstSensor, STF_U6 u6FocusDistance);
} ST_SENSOR, *PST_SENSOR;
The following table describes the fields in the above code block.
Table 1. ST_SENSOR Field Description
Field Description
Data Fields
pstSensorHandle Sensor API handle
enState Sensor running state
u6Width Output image width
u6Height Output image height
u8Imager Imager ID. No longer in use
u6VerticalTotal Number of lines including blanking
enBayerFormat Mosaic of the sensor
u8SensorContexts Sensor contexts. No longer in use
u8BitDepth Bits per pixel
dFrameRate Sensor default frame rate
dCurrentFPS Frame rate programmed in the sensor
u32WellDepth Number of electrons can be held by the sensor wells before clipping. No longer in use
dReadNoise Standard deviation of noise when reading pixel value off a sensor in electrons. No longer in use
dAperture Aperture f/# of the attached lens. No longer in use
u6FocalLength Focal length of the lens in millimetres. No longer In use
u32ProgrammedExposure Exposure time programmed in the sensor
dProgrammedGain Gain programmed in the sensor
u6ProgrammedFocus Focus distance set in the sensor. No longer in use
u32MinExposure Minimum exposure times
u32MaxExposure Maximum exposure times
u6MinFocus Minimum focus distance. No longer in use
u6MaxFocus Maximum focus distance. No longer in use
dMinGain Minimum exposure gain
dMaxGain Maximum exposure gain
bFocusSupported Variable focus support status. No longer in use
Function Pointers
*StateName Get sensor state name
*GetSensorNames Populate a list with the available sensors from Sensor API
*GetSensorId Get sensor ID from a name
*Init Sensor structure initialization
*Destroy Destroy a sensor through a given identifier
*GetHandle Access to sensors API handle
*GetState Get the sensor state
*GetInfo Get the sensor information
*GetModeIdx Get the sensor mode index
*GetMode Get some mode information (including if flipping is supported)
*SetMode Set the sensor mode
*GetInterfaceInfo Get the sensor connection data bus and I2C hardware information
*Configure Configure the sensor with a selected mode
*Insert Access to the Sensor API insert function. No longer in use
*WaitProcessed Access to the Sensor API waitProcessed function. No longer in use
*Enable Start transmission of the data from the sensor. In the V4L2 driver, only changed the sensor state
*Disable Stop transmission of the data from the sensor. In the V4L2 driver, only changed the sensor state
*Reset Reset the sensor. In the V4L2 driver, only changed the sensor state
*GetStatus Get status value in the sensor
*GetReg Get the sensor register value
*SetReg Program the value to the register of sensor
*GetFlipMirror Get flip and mirror value in the sensor
*SetFlipMirror Set flip and mirror value in the sensor
*GetFixedFPS Get the fixed FPS value in the sensor
*SetFPS Set the FPS value in the sensor
*GetSnapShotResolution Get the snapshot resolution value in the sensor. No longer in use
*SetResolution Set the resolution value to the sensor. No longer in use
*GetMinExposure Get minimum exposure time value programmable in the sensor
*GetMaxExposure Get maximum exposure time value programmable in the sensor
*GetExposureRange Get minimum and maximum exposure time value programmable in the sensor
*GetExposure Get the exposure time programmed in the sensor
*SetExposure Program the exposure time in the sensor
*GetMinGain Get minimum gain value programmable in the sensor
*SetMinGain Set the minimum gain value programmable in the sensor
*GetMaxGain Set the minimum gain value programmable in the sensor
*SetMaxGain Set the maximum gain value programmable in the sensor
*GetGainRange Get minimum and maximum gain value programmable in the sensor
*SetIsoLimit Set minimum and maximum gain value programmable in the sensor according to the ISO value
*GetGain Get the gain value from the sensor
*SetGain Set the gain value in the sensor
*SetExposureAndGain Program the exposure time and gain in the sensor
*GetFocusSupported Get state of driver support for variable focus. No longer in use
*GetMinFocus Get minimum focus distance. No longer in use
*GetMaxFocus Get maximum focus distance. No longer in use
*GetFocusDistance Get the current focus distance. No longer in use
*SetFocusDistance Set focus distance in the sensor in millimetre. No longer in use

SENSOR_STATUS

Returned by ST_SENSOR::GetStatus(), the SENSOR_STATUS object provides a snapshot of the sensor's current operating state.

The following code block shows the data structure for the sensor status structure. 
typedef struct _SENSOR_STATUS {
    STF_U8 u8CurrentMode;
    STF_U8 u8Flipping;
    STF_DOUBLE dCurrentFps;
    SENSOR_STATE enState;
} SENSOR_STATUS, *PSENSOR_STATUS;
The following table describes the fields in the above code block.
Table 2. Sensor Status Field Description
Field Description
u8CurrentMode Mode ID that the sensor is currently running in, this is an index to the list of modes returned by calling the GetSensorMode function
u8Flipping Select flip and mirror information
dCurrentFps Currently sensor output frame rate
enState Sensor running state

SENSOR_MODE

Returned by ST_SENSOR::GetMode(), the SENSOR_MODE object describes the parameters of one sensor operating mode (such as resolution, frame rate, and exposure range).

The following code block shows the data structure for the sensor mode structure. 
typedef struct _SENSOR_MODE {
    STF_U8 u8BitDepth;
    STF_U16 u16Width;
    STF_U16 u16Height;
    STF_DOUBLE dFrameRate;
    STF_DOUBLE dPixelRate;
    STF_U16 u16HorizontalTotal;
    STF_U16 u16VerticalTotal;
    STF_U8 u8SupportFlipping;
    STF_U32 u32ExposureMin;
    STF_U32 u32ExposureMax;
    STF_DOUBLE dExposureMin;
    STF_U8 u8MipiLanes;
} SENSOR_MODE, *PSENSOR_MODE;
The following table describes the fields in the above code block.
Table 3. DRM Buffer Field Description
Field Description
u8BitDepth The bit depth in the sensor mode
u16Width Width of output in pixels
u16Height Height of output in pixels
dFrameRate Frame rate in Hz
dPixelRate The pixel rate in the sensor mode
u16HorizontalTotal Horizontal total size (including blanking) in pixels
u16VerticalTotal Vertical total size (including blanking) in pixels
u8SupportFlipping Support flipping when enabling
u32ExposureMin Minimum exposure time (integer type)
u32ExposureMax Maximum exposure time
dExposureMin Minimum exposure time (double type)
u8MipiLanes MIPI lanes for MIPI interface sensor

SENSOR_INTFC

Returned by ST_SENSOR::GetInterfaceInfo(), the SENSOR_INTFC object describes the physical connection between the sensor and the SoC including data bus type, I2C configuration, and control pins.

The following code block shows the data structure for the sensor interface structure. 
typedef struct _SENSOR_INTFC {
    STF_U8 u8DataInterface;
    STF_U8 u8I2cChannel;
    STF_U8 u8I2cSlaveAddrbit;
    STF_U8 u8I2cRegAddrBit;
    STF_U8 u8I2cRegDataBit;
    STF_U16 u16I2cSlaveAddr;
    STF_S16 s16PowerGpioId;
    STF_U16 u16PowerGpioInitLevel;
    STF_S16 s16ResetGpioId;
    STF_U16 u16ResetGpioInitLevel;
    STF_U16 u16ResetIntervalTime;
    STF_U8 u8SensorPolarity;
} SENSOR_INTFC, *PSENSOR_INTFC;
The following table describes the fields in the above code block.
Table 4. SENSOR_INTFC
Field Description
u8DataInterface Indicate which data interface will be used. 0: DVP, 1: MIPI
u8I2cChannel Indicate which I2C channel will be used. Range: 0 - 3
u8I2cSlaveAddrbit1 Indicate the slave address bit. 0: 7 bits, 1: 10 bits. Not used in the V4L2 driver
u8I2cRegAddrBit1 Indicate the sensor register address bit. 0: 8 bits, 1: 16 bits. Not used in the V4L2 driver
u8I2cRegDataBit1 Indicate the sensor register data bit. 0: 8 bits, 1: 16 bits. Not used in the V4L2 driver
u16I2cSlaveAddr Indicate the slave address of sensor.
s16PowerGpioId1 Power control pin. Not used in the V4L2 driver
u16PowerGpioInitLevel1 Power control pin initialize value. Not used in the V4L2 driver
s16ResetGpioId1 Reset pin. Not used in the V4L2 driver
u16ResetGpioInitLevel1 Reset pin initialize value. Not used in the V4L2 driver
u16ResetIntervalTime1 Reset pin hold timing. Not used in the V4L2 driver
u8SensorPolarity Sensor polarity status
Note:

  1. The field items are for proprietary driver only.

SENSOR_INFO

Returned by ST_SENSOR::GetInfo(), the SENSOR_INFO object provides a comprehensive snapshot of the sensor, including its identity, current state, and mode configuration.

The following code block shows the data structure for the sensor information structure. 
typedef struct _SENSOR_INFO {
    enum MOSAICType enBayerOriginal;
    enum MOSAICType enBayerEnabled;
    char pszSensorName[SENSOR_INFO_NAME_MAX]; 
    char pszSensorVersion[SENSOR_INFO_VERSION_MAX];
    STF_DOUBLE dNumber;
    STF_U16 u16FocalLength;
    STF_U32 u32WellDepth;
    STF_DOUBLE dReadNoise;
    STF_U8 u8Imager;
    STF_BOOL8 bBackFacing;
    SENSOR_STATUS stStatus;
    SENSOR_MODE stMode;
    STF_U32 u32ModeCount;
    EN_EXPO_GAIN_METHOD enExposureGainMethod;
} SENSOR_INFO, *PSENSOR_INFO;
The following table describes the fields in the above code block.
Table 5. Sensor Information Field Description
Field Description
enBayerOriginal Original CFA filter layout (before flipping)
enBayerEnabled Enabled CFA filter layout (including flipping)
pszSensorName Text name for the sensor for easy identification
pszSensorVersion To be used where multiple versions of the sensor exists
dNumber1 Aperture of the attached lens. No longer in use
u16FocalLength1 Focal length of the lens. No longer in use
u32WellDepth1 Number of electrons can be held by the sensor wells before clipping. No longer in use
dReadNoise1 Standard deviation of noise when reading pixel value off a sensor in electrons. No longer in use
u8Imager1 Imager ID. No longer in use
bBackFacing1 Is this a back or front of facing camera? No longer in use
stStatus Sensor status
stMode Sensor mode information
u32ModeCount Indicate how many modes are supported in this sensor
enExposureGainMethod Indicate how to program the exposure time and gain

SENSOR_FUNCS

The SENSOR_FUNCS object is the function table that each sensor driver must implement.

The following code block shows the data structure of this object. 
typedef struct _SENSOR_FUNCS {
    /* ---- Mode Configuration ---- */
    STF_S8     (*GetModeIdx)(SENSOR_HANDLE *pstHandle, STF_U16 u16Width, STF_U16 u16Height);
    STF_RESULT (*GetMode)(SENSOR_HANDLE *pstHandle, STF_U8 u8ModeIdx, SENSOR_MODE *pstModes);
    STF_RESULT (*SetMode)(SENSOR_HANDLE *pstHandle, STF_U8 u8ModeIdx, STF_U8 u8Flipping);

    /* ---- Lifecycle ---- */
    STF_RESULT (*Enable)(SENSOR_HANDLE *pstHandle);
    STF_RESULT (*Disable)(SENSOR_HANDLE *pstHandle);
    STF_RESULT (*Destroy)(SENSOR_HANDLE *pstHandle);

    /* ---- Status & Info ---- */
    STF_RESULT (*GetState)(SENSOR_HANDLE *pstHandle, SENSOR_STATUS *pstStatus);
    STF_RESULT (*GetInterfaceInfo)(SENSOR_HANDLE *pstHandle, SENSOR_INTFC *pstInterface);
    STF_RESULT (*GetInfo)(SENSOR_HANDLE *pstHandle, SENSOR_INFO *pstInfo);

    /* ---- Register Access ---- */
    STF_RESULT (*GetRegister)(SENSOR_HANDLE *pstHandle, STF_U16 u16RegAddr, STF_U16 *pu16RegVal, STF_U8 u8Context);
    STF_RESULT (*SetRegister)(SENSOR_HANDLE *pstHandle, STF_U16 u16RegAddr, STF_U16 u16RegVal, STF_U8 u8Context);

    /* ---- Gain Control ---- */
    STF_RESULT (*GetGainRange)(SENSOR_HANDLE *pstHandle, STF_DOUBLE *pdMin, STF_DOUBLE *pdMax, STF_U8 *pu8Contexts);
    STF_RESULT (*GetCurrentGain)(SENSOR_HANDLE *pstHandle, STF_DOUBLE *pdCurrentGain, STF_U8 u8Context);
    STF_RESULT (*SetGain)(SENSOR_HANDLE *pstHandle, STF_DOUBLE dGain, STF_U8 u8Context);

    /* ---- Exposure Control ---- */
    STF_RESULT (*GetExposureRange)(SENSOR_HANDLE *pstHandle, STF_U32 *pu32Min, STF_U32 *pu32Max, STF_U8 *pu8Contexts);
    STF_RESULT (*GetExposure)(SENSOR_HANDLE *pstHandle, STF_U32 *pu32Exposure, STF_U8 u8Context);
    STF_RESULT (*SetExposure)(SENSOR_HANDLE *pstHandle, STF_U32 u32Exposure, STF_U8 u8Context);

    /* ---- Combined Exposure + Gain ---- */
    STF_RESULT (*SetExposureAndGain)(SENSOR_HANDLE *pstHandle, STF_U32 u32Exposure, STF_DOUBLE dGain, STF_U8 u8Context);

    /* ---- Orientation & Frame Rate ---- */
    STF_RESULT (*SetFlipMirror)(SENSOR_HANDLE *pstHandle, STF_U8 u8Flag);
    STF_RESULT (*GetFixedFPS)(SENSOR_HANDLE *pstHandle, STF_U16 *pu16Fixed);
    STF_RESULT (*SetFPS)(SENSOR_HANDLE *pstHandle, STF_DOUBLE dFps);

    /* ---- Snapshot & Reset ---- */
    STF_RESULT (*GetSnapRes)(SENSOR_HANDLE *pstHandle, ST_RES_LIST *pstReslist);
    STF_RESULT (*Reset)(SENSOR_HANDLE *pstHandle);

    /* ---- Deprecated (do not implement) ---- */
    STF_RESULT (*GetFocusRange)(SENSOR_HANDLE *pstHandle, STF_U16 *pu16Min, STF_U16 *pu16Max);
    STF_RESULT (*GetCurrentFocus)(SENSOR_HANDLE *pstHandle, STF_U16 *pu16CurrentFocus);
    STF_RESULT (*SetFocus)(SENSOR_HANDLE *pstHandle, STF_U16 u16Focus);
    STF_RESULT (*ConfigureFlash)(SENSOR_HANDLE *pstHandle, STF_BOOL8 bAlwaysOn, STF_S16 s16FrameDelay, STF_S16 s16Frames, STF_U16 u16FlashPulseWidth);
    STF_RESULT (*Insert)(SENSOR_HANDLE *pstHandle);
    STF_RESULT (*WaitProcessed)(SENSOR_HANDLE *pstHandle);
    STF_RESULT (*SetResolution)(SENSOR_HANDLE *pstHandle, STF_U16 u16ImgW, STF_U16 U16ImgH);
} SENSOR_FUNCS, *PSENSOR_FUNCS;
The following table describes the fields in the above code block.
Table 6. Sensor Function Field Description
Field Description
*GetModeIdx Get the sensor mode index
*GetMode Fill in a structure detailing the modes supported by the sensor
*GetState Get the current state of the sensor
*GetInterfaceInfo Get the sensor's connection data bus and I2C hardware information
*SetMode Set the sensor mode
*Enable Enable the sensor
*Disable Disable the sensor
*Destroy Release and de-initialize the sensor
*GetInfo Get information about the sensor
*GetRegister Read the sensor register value
*SetRegister Set the sensor register value
*GetGainRange Get the range of gain settings that the sensor can support
*GetCurrentGain Get the current gain setting from sensor
*SetGain Set the current gain setting to the sensor
*GetExposureRange Get the range of exposures the sensor can use
*GetExposure Query the sensor for the current exposure period
*SetExposure Set the sensor to the requested exposure period
*SetFlipMirror Set flip and mirror value in the sensor
*GetFixedFPS Get the fixed FPS value in the sensor
*SetFPS Set the FPS value in the sensor
*SetExposureAndGain Program the exposure time and gain in the sensor
*Reset Reset the sensor.