overview
In the previous section, we have defined a unified error code and data structure to shield the implementation details of different Ingenic chips. The preparatory work has been done. Next, we need to define the public base class of Ingenic's underlying API interface. The interfaces given in the common base class are all pure virtual functions. Different IPC chip solutions, such as T31, T40, and T41, are derived from the common base class and implement these virtual functions.
common base class
First of all, we need to think about what granularity is used to define the interface of the common base class? The granularity is too fine, it is cumbersome to use, and more interfaces need to be called to complete a function. The granularity is too coarse, the upper layer is not flexible enough, and some interfaces may not be provided. Therefore, when we design the interface of the common base class, we need to consider it comprehensively, which not only provides enough flexibility, but also meets the convenience of calling.
ISVP-SDK provides application libraries for application layer development, including: imp library and sysutils library. The imp library is divided into functional modules, and different modules are defined in different header files. For example: data binding and system control functions are in imp_system.h, H264, H265, JPEG encoding functions are in imp_encoder.h. We can also define interfaces based on these modules, so that the use of interfaces is clearer. At the same time, we also need to consider how the upper layer uses the interface, and the encapsulated interface can meet the convenience of the upper layer call.
The common base classes defined in the MPP_API_Base.h file are as follows.
#pragma once
#include "MPP_API_Types.h"
class CMppApi_Base
{
public:
CMppApi_Base() {}
virtual ~CMppApi_Base() {}
virtual int Sys_Init(const TMppSystemParam ¶m) = 0;
virtual int Sys_Deinit() = 0;
virtual int Sys_BindItem(const TMppBindItem &srcItem, const TMppBindItem &dstItem) = 0;
virtual int Sys_UnbindItem(const TMppBindItem &srcItem, const TMppBindItem &dstItem) = 0;
virtual int Sys_GetChipID(std::string &strID) = 0;
virtual int Sys_GetRtcTime(TMppRtcTime &rtcTime) = 0;
virtual int Sys_SetRtcTime(const TMppRtcTime &rtcTime) = 0;
virtual int Isp_SetHue(unsigned char ucPercent, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetContrast(unsigned char ucPercent, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetBrightness(unsigned char ucPercent, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetSaturation(unsigned char ucPercent, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetSharpness(unsigned char ucPercent, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_GetRunningMode(bool &bNight, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetRunningMode(bool bNight, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetHorFlip(bool bEnable, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetVerFlip(bool bEnable, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetHorVerFlip(bool bEnable, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetAntiFlicker(IMppAntiflickerMode mode, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_GetExposureAttr(TMppIspExposureAttr &expAttr, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_GetWhiteBalance(TMppIspWBAttr &wbAttr, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_SetWhiteBalance(const TMppIspWBAttr &wbAttr, unsigned int uiCameraChannel = 0) = 0;
virtual int Isp_GetGlobalWhiteBalance(TMppIspWBAttr &wbAttr, unsigned int uiCameraChannel = 0) = 0;
virtual int Fs_Create(int nFsChn, unsigned int uiFrameRate, unsigned int uiWidth, unsigned int uiHeight,
bool bExpandNrVbs = false) = 0;
virtual int Fs_Destroy(int nFsChn) = 0;
virtual int Fs_Enable(int nFsChn) = 0;
virtual int Fs_Disable(int nFsChn) = 0;
virtual int Fs_SetDepth(int nFsChn, int nDepth) = 0;
virtual int Fs_GetFrame(int nFsChn, unsigned char *pFrame, unsigned int &uiFrameLen,
unsigned int &uiWidth, unsigned int &uiHeight) = 0;
virtual int Enc_CreateGroup(int nGrpChn) = 0;
virtual int Enc_DestroyGroup(int nGrpChn) = 0;
virtual int Enc_CreateChannel(int nGrpChn, int nEncChn, const TMppEncChannelParam ¶m) = 0;
virtual int Enc_DestroyChannel(int nEncChn) = 0;
virtual int Enc_StartRecvPic(int nEncChn) = 0;
virtual int Enc_StopRecvPic(int nEncChn) = 0;
virtual int Enc_GetFd(int nEncChn) = 0;
virtual int Enc_PollingStream(int nEncChn, unsigned int uiTimeoutMs = 10) = 0;
virtual int Enc_GetStream(int nEncChn, unsigned char *pFrame, unsigned int &uiFrameLen,
unsigned long long &ui64TimestampUs, bool &bKeyFrame) = 0;
virtual int Enc_RequestIDR(int nEncChn) = 0;
virtual int Enc_FlushStream(int nEncChn) = 0;
virtual int Enc_SetFrameRate(int nEncChn, unsigned int uiFrameRate) = 0;
virtual int Enc_SetBitrate(int nEncChn, unsigned int uiBitrateKbps) = 0;
virtual int Enc_SetKeyFrameInterval(int nEncChn, unsigned int uiKeyFrameInterval) = 0;
virtual int Enc_SetBitrateCtrlMode(int nEncChn, IMppVideoBitrateCtrlMode mode) = 0;
virtual int Enc_SetJpegQualityPercent(int nEncChn, unsigned char ucQualityPercent) = 0;
virtual int Osd_CreateGroup(int nGrpChn) = 0;
virtual int Osd_DestroyGroup(int nGrpChn) = 0;
virtual int Osd_CreateRegion(int nGrpChn, int &nRgnChn) = 0;
virtual int Osd_DestroyRegion(int nGrpChn, int nRgnChn) = 0;
virtual int Osd_SetRegionAttr(int nRgnChn, const TMppOsdRegionAttr &attr) = 0;
virtual int Osd_SetGroupRegionAttr(int nGrpChn, int nRgnChn, const TMppOsdGroupRegionAttr &attr) = 0;
virtual int Osd_ShowRegion(int nGrpChn, int nRgnChn, bool bShow) = 0;
virtual int Osd_UpdateRegionData(int nRgnChn, const TMppOsdRegionData &data) = 0;
virtual int Ain_SetPubAttr(unsigned int uiSampleRate, bool bStereo, unsigned int uiSamplesPerFrame,
bool bDigitalMic = false) = 0;
virtual int Ain_EnableDevice() = 0;
virtual int Ain_DisableDevice() = 0;
virtual int Ain_EnableChannel() = 0;
virtual int Ain_DisableChannel() = 0;
virtual int Ain_GetFrame(unsigned char *pFrame, unsigned int &uiFrameLen, unsigned int uiTimeoutMs = 10) = 0;
virtual int Ain_SetVolume(unsigned char ucVolumePercent) = 0;
virtual int Ain_SetGain(unsigned char ucGainPercent) = 0;
virtual int Ain_EnableAec(bool bDefaultSpeaker = true) = 0;
virtual int Ain_DisableAec() = 0;
virtual int Ain_EnableNs(IMppNoiseSuppressLevel level) = 0;
virtual int Ain_DisableNs() = 0;
virtual int Aenc_RegisterEncoder(IMppAudioCodecAlg type) = 0;
virtual int Aenc_UnregisterEncoder(IMppAudioCodecAlg type) = 0;
virtual int Aenc_CreateChannel(IMppAudioCodecAlg type) = 0;
virtual int Aenc_DestroyChannel() = 0;
virtual int Aenc_SendFrame(unsigned char *pFrame, unsigned int uiFrameLen) = 0;
virtual int Aenc_GetStream(unsigned char *pFrame, unsigned int &uiFrameLen,
unsigned long long &ui64TimestampUs, unsigned int uiTimeoutMs = 10) = 0;
virtual int Aout_SetPubAttr(unsigned int uiSampleRate, bool bStereo, unsigned int uiSamplesPerFrame,
bool bDefaultSpeaker = true) = 0;
virtual int Aout_EnableDevice() = 0;
virtual int Aout_DisableDevice() = 0;
virtual int Aout_EnableChannel() = 0;
virtual int Aout_DisableChannel() = 0;
virtual int Aout_SendFrame(unsigned char *pFrame, unsigned int uiFrameLen) = 0;
virtual int Aout_SetVolume(unsigned char ucVolumePercent) = 0;
virtual int Aout_SetGain(unsigned char ucGainPercent) = 0;
virtual int Aout_FlushBuf() = 0;
virtual int Aout_ClearBuf() = 0;
virtual int Adec_RegisterDecoder(IMppAudioCodecAlg type) = 0;
virtual int Adec_UnregisterDecoder(IMppAudioCodecAlg type) = 0;
virtual int Adec_CreateChannel(IMppAudioCodecAlg type) = 0;
virtual int Adec_DestroyChannel() = 0;
virtual int Adec_SendStream(unsigned char *pFrame, unsigned int uiFrameLen) = 0;
virtual int Adec_GetFrame(unsigned char *pFrame, unsigned int &uiFrameLen, unsigned int uiTimeoutMs = 10) = 0;
virtual int Adec_ClearBuf() = 0;
virtual int Ivs_CreateGroup(int nGrpChn) = 0;
virtual int Ivs_DestroyGroup(int nGrpChn) = 0;
virtual int Ivs_CreateChannel(int nGrpChn, int nIvsChn, void *pHandler) = 0;
virtual int Ivs_DestroyChannel(int nIvsChn) = 0;
virtual int Ivs_StartRecvPic(int nIvsChn) = 0;
virtual int Ivs_StopRecvPic(int nIvsChn) = 0;
virtual int Ivs_PollingResult(int nIvsChn, int nTimeoutMs = -1) = 0;
virtual int Ivs_GetResult(int nIvsChn, void **ppResult) = 0;
virtual int Ivs_ReleaseResult(int nIvsChn, void *pResult) = 0;
virtual int Ivs_GetParam(int nIvsChn, void *pParam) = 0;
virtual int Ivs_SetParam(int nIvsChn, void *pParam) = 0;
virtual int Utils_GetFsChn(unsigned int uiCameraChannel, IMppVideoStreamType type) = 0;
virtual int Utils_GetEncGrp(unsigned int uiCameraChannel, IMppVideoStreamType type) = 0;
virtual int Utils_GetEncChn(unsigned int uiCameraChannel, IMppVideoStreamType type, bool bJpeg) = 0;
virtual int Utils_GetOsdGrp(unsigned int uiCameraChannel, IMppVideoStreamType type) = 0;
virtual int Utils_GetIvsGrp(unsigned int uiCameraChannel) = 0;
};Interface Description
In the above header file, we define a lot of pure virtual function interfaces according to the module, and we will introduce them one by one below.
□ System layer interface
Sys_Init: System initialization interface, which needs to pass in camera information (multiple are supported) and the size of the OSD memory pool.
Sys_Deinit: System deinitialization interface.
Sys_BindItem: The interface for system binding, which supports the binding of two modules, and the data is automatically streamed after binding.
Sys_UnbindItem: The interface for system unbind, which supports unbind two modules.
Sys_GetChipID: the interface to get the unique ID of the chip.
Sys_GetRtcTime: Interface to get the system RTC time (requires hardware to support RTC related circuits).
Sys_SetRtcTime: Interface to set the system RTC time (requires hardware to support RTC related circuits).
□ ISP interface
Isp_SetHue: Set the hue of a channel, the value range is from 0 to 100.
Isp_SetContrast: Set the contrast of a channel, the value range is 0 to 100.
Isp_SetBrightness: Set the brightness of a channel, the value range is 0 to 100.
Isp_SetSaturation: Set the saturation of a channel, the value range is from 0 to 100.
Isp_SetSharpness: Set the sharpness of a certain channel, the value range is from 0 to 100.
Isp_GetRunningMode: Get the running mode of a channel ISP, whether it is day or night.
Isp_SetRunningMode: Set the running mode of a channel ISP is day or night.
Isp_SetHorFlip: Set whether the image of a certain channel is flipped horizontally.
Isp_SetVerFlip: Set whether the image of a certain channel is vertically flipped.
Isp_SetHorVerFlip: Set whether the image of a certain channel is flipped horizontally or vertically.
Isp_SetAntiFlicker: Set the anti-flicker mode of a certain channel image.
Isp_GetExposureAttr: Get the exposure attribute of a channel.
Isp_GetWhiteBalance: Get the white balance information of a channel.
Isp_SetWhiteBalance: Set the white balance information of a certain channel.
Isp_GetGlobalWhiteBalance: Get the global white balance information of a channel.
□ Frame Source interface
Fs_Create: Create a Frame Source channel based on the specified frame rate, resolution and other information.
Fs_Destroy: Destroy the specified Frame Source channel.
Fs_Enable: Enable the specified Frame Source channel.
Fs_Disable: Disable the specified Frame Source channel.
Fs_SetDepth: Set the depth value of the specified Frame Source channel (used to obtain video raw data, such as: YUV data).
Fs_GetFrame: Get the video raw data frame of the specified Frame Source channel.
□ Coding interface
Enc_CreateGroup: Create an encoded group.
Enc_DestroyGroup: Destroys an encoded group.
Enc_CreateChannel: Create an encoding channel within a specified group. When creating a channel, parameters such as encoding profile, resolution, and frame rate can be passed in.
Enc_DestroyChannel: Destroy the encoding channel.
Enc_StartRecvPic: Start receiving pictures of the specified encoding channel.
Enc_StopRecvPic: Stop receiving pictures from the specified encoding channel.
Enc_GetFd: Get the file descriptor of the specified encoding channel, which is used to select for IO multiplexing.
Enc_PollingStream: Query whether the stream of the specified encoding channel is ready, and the timeout period can be set in milliseconds.
Enc_GetStream: Get a frame of stream data of the specified encoding channel.
Enc_RequestIDR: Request the IDR frame of the specified encoding channel.
Enc_FlushStream: Flush the old code stream in the specified encoding channel, and start encoding with IDR frame.
Enc_SetFrameRate: Set the frame rate of the specified encoding channel.
Enc_SetBitrate: Set the bit rate of the specified encoding channel.
Enc_SetKeyFrameInterval: Set the key frame interval of the specified encoding channel.
Enc_SetBitrateCtrlMode: Set the rate control mode of the specified encoding channel to be CBR, VBR, or ABR.
Enc_SetJpegQualityPercent: Set the quality of the JPEG image of the specified encoding channel, the value range is 0 to 100.
□ OSD interface
Osd_CreateGroup: Create OSD groups.
Osd_DestroyGroup: Destroy the OSD group.
Osd_CreateRegion: Create a region within the specified group.
Osd_DestroyRegion: Destroy the region within the specified group.
Osd_SetRegionAttr: Set the attributes of a region, including: region type, location, data, etc.
Osd_SetGroupRegionAttr: Set the region attributes of a group, including: whether to display, zoom ratio, level, etc.
Osd_ShowRegion: Whether to display a certain region.
Osd_UpdateRegionData: Update the data of a certain region. For example: when the time is superimposed on the video screen, the value of the time changes, and this interface needs to be called to update the time in the area.
□ Input audio interface
Ain_SetPubAttr: Set the public attributes of the input audio, including: sampling rate, whether it is stereo, the number of samples per frame, etc. Before calling other interfaces for input audio, this interface must be called first.
Ain_EnableDevice: Enable input audio device.
Ain_DisableDevice: Disables the input audio device.
Ain_EnableChannel: Enable input audio channel.
Ain_DisableChannel: Disables the input audio channel.
Ain_GetFrame: Get the raw PCM data of the input audio channel, which can be used in algorithms such as sound detection.
Ain_SetVolume: Set the digital gain of the input audio channel, the value range is from 0 to 100.
Ain_SetGain: Set the analog gain of the input audio channel, the value range is 0 to 100. The value of analog gain and digital gain needs to be adjusted according to the final product structure. If it is too small, the other party cannot hear clearly, and if it is too large, it will easily cause popping sound and background noise that cannot be removed.
Ain_EnableAec: Enables echo cancellation for the input audio channel.
Ain_DisableAec: Disables echo cancellation for the input audio channel.
Ain_EnableNs: Enables noise suppression for input audio channels.
Ain_DisableNs: Disables noise suppression for input audio channels.
□ Audio coding interface
Aenc_RegisterEncoder: Register audio encoder. By default, the SDK only supports encoding algorithms such as G711A, G711U, and ADPCM_ORG_DVI4, and does not support encoding algorithms such as ADPCM_DVI and AAC. If you need to support ADPCM_DVI, AAC and other algorithms, you need to call this interface to register the corresponding audio encoder.
Aenc_UnregisterEncoder: Unregister the audio encoder.
Aenc_CreateChannel: Create an audio encoding channel.
Aenc_DestroyChannel: Destroy the audio encoding channel.
Aenc_SendFrame: Send bare PCM data to the audio encoding channel, there will be a queue inside the SDK to cache the data, and then encode and output.
Aenc_GetStream: Get the encoded data stream from the audio encoding channel.
□ Output audio interface
Aout_SetPubAttr: Set the public attributes of the output audio, including: sampling rate, stereo or not, number of samples per frame, etc. This interface must be called before calling other interfaces that output audio.
Aout_EnableDevice: Enable output audio device.
Aout_DisableDevice: Disable the output audio device.
Aout_EnableChannel: Enable output audio channel.
Aout_DisableChannel: Disable the output audio channel.
Aout_SendFrame: Sends raw PCM data to the output audio channel.
Aout_SetVolume: Set the digital gain of the output audio channel, the value range is from 0 to 100.
Aout_SetGain: Set the analog gain of the output audio channel, the value range is from 0 to 100. The value of analog gain and digital gain needs to be adjusted according to the final product structure. If it is too small, it is hard to hear, and if it is too large, it will easily produce popping sound and irremovable background noise.
Aout_FlushBuf: Wait for all data in the output audio channel to be played.
Aout_ClearBuf: Clear the data buffer in the output audio channel.
□ Audio decoding interface
Adec_RegisterDecoder: Register audio decoder. By default, the SDK only supports decoding algorithms such as G711A, G711U, and ADPCM_ORG_DVI4, and does not support decoding algorithms such as ADPCM_DVI and AAC. If you need to support ADPCM_DVI, you need to call this interface to register the corresponding audio decoder. If you need to support AAC, you don’t need to call this interface to register. This is because there are defects and problems in decoding AAC using the registration mechanism of the SDK, and AAC cannot be decoded normally.
Adec_UnregisterDecoder: Unregister the audio decoder.
Adec_CreateChannel: Create an audio decoding channel. When AAC needs to be supported, the parameters can be passed to MppAudioCodecAlg_AAC.
Adec_DestroyChannel: Destroy the audio decoding channel.
Adec_SendStream: Send the audio data stream to the audio decoding channel, there will be a queue inside the SDK to cache the data, and then decode and output.
Adec_GetFrame: Get the decoded raw PCM data from the audio decoding channel.
Adec_ClearBuf: Clear the data buffer in the audio decoding channel.
□IVS interface
Ivs_CreateGroup: Create IVS grouping.
Ivs_DestroyGroup: Destroy the IVS group.
Ivs_CreateChannel: Create a channel within the specified group.
Ivs_DestroyChannel: Destroy the IVS channel.
Ivs_StartRecvPic: Start receiving pictures of the specified IVS channel.
Ivs_StopRecvPic: Stop receiving pictures from the specified IVS channel.
Ivs_PollingResult: Query whether the result of the specified IVS channel is ready, and the timeout period can be set in milliseconds.
Ivs_GetResult: Get the result of the specified IVS channel.
Ivs_ReleaseResult: Release the result of the specified IVS channel.
Ivs_GetParam: Get the parameters of the specified IVS channel.
Ivs_SetParam: Set the parameters of the specified IVS channel.
□ Practical interface
Utils_GetFsChn: Get the Frame Source channel of the specified camera channel and stream type.
Utils_GetEncGrp: Get the encoding group of the specified camera channel and stream type.
Utils_GetEncChn: Get the encoding channel of the specified camera channel and stream type.
Utils_GetOsdGrp: Get the OSD group of the specified camera channel and stream type.
Utils_GetIvsGrp: Get the IVS group of the specified camera channel.
The content of this section will be introduced here first. In the next section, we will introduce how to support ADPCM_DVI, AAC and other encoding and decoding algorithms in the Ingenic chip solution.