2024年1月3日发(作者：)

Step#2: initialize the decoder 10Step#3: invoker the decoding 10Step#4: control the decoding 11Decoder Option List: 12Decoder Parameter List: 13Decoder Usage Example: 13

Revisions historyDateVersionAuthorDescription12/23/20130.1Sijia Chen, Wayne LiuInitial version

12/25/20130.2Sijia ChenAdd encoder return value explanation12/25/20130.3Sijia ChenAdd explanation on range of some parameters in encoder03/04/20140.4Karina LiInterface and parameters update05/23/20141.0Wayne Liu, Karina LiUpdate for v1.0 release

Encoder Interface Usage:Step#1: create and destroy the encoderint WelsCreateSVCEncoder(ISVCEncoder** ppEncoder);void WelsDestroySVCEncoder(ISVCEncoder* pEncoder);

Step#2: initialize the encoder/* Initilaize encoder by using base parameters. */virtual int Initialize (const SEncParamBase* pParam) = 0;/*Initilaize encoder by using extension parameters. If the user needs to set the more details, refer to use this interface. */virtual int InitializeExt (const SEncParamExt* pParam) = 0;

/* Get the default extension parameters . some time the user doesn’t care about all of the parameters. So he can get use the i */

virtual int GetDefaultParams (SEncParamExt* pParam) = 0;

virtual int Unintialize() = 0;Step#3: invoker the encoding/* * return: 0 - success; otherwise - failed; */virtual int EncodeFrame(const SSourcePicture* kpSrcPic, SFrameBSInfo* pBsInfo) = 0;

SSourcePicture:Format

Parameter NameMeaning/ConstraintintiColorFormatthe input image color space format, currently only supports videoFormatI420intiStride[4]The stride of picture buffer

unsigned charpData[4]Pointer to the source data

intiPicWidthwidth of picture in luminance samplesintiPicHeightheight of picture in luminance samplesLong longuiTimeStampTime stamp of the frame.

// kpSrc = the pointer to the source luminance plane// chrominance data:

// CbData = kpSrc + m_iMaxPicWidth * m_iMaxPicHeight;// CrData = CbData + (m_iMaxPicWidth * m_iMaxPicHeight)/4;//the application calling this interface needs to ensure the data validation between the location of [kpSrc, kpSrc+framesize-1]

Step#4: control the encodingThe upper layer application should ensure threading safety between calling these control interfaces and calling the encoding.

/* * return: 0 - success; otherwise - failed; */virtual int PauseFrame(const SSourcePicture* kpSrcPic, SFrameBSInfo* pBsInfo) = 0;/* * return: 0 - success; otherwise - failed; */virtual int ForceIntraFrame(bool bIDR) = 0;/*********************************************************************** * InDataFormat, IDRInterval, SVC Encode Param, Frame Rate, Bitrate,..**************************** ******************************************//* * return: CM_RETURN: 0 - success; otherwise - failed; */virtual int SetOption(ENCODER_OPTION eOptionId, void* pOption) = 0;virtual int GetOption(ENCODER_OPTION eOptionId, void* pOption) = 0;

Encoder Option List:

int CWelsH264SVCEncoder::SetOption(ENCODER_OPTION eOptionId, void* pOption)Option IDInput FormatMeaning/ConstraintENCODER_OPTION_SVC_ENCODE_PARAM_BASEStructure of Base Param

ENCODER_OPTION_SVC_ENCODE_PARAM_EXTStructure of Extension Param

ENCODER_OPTION_IDR_INTERVALintIDR period,0/-1 means no Intra period (only the first frame)>0 means the desired IDR period, must be multiple of (2^temporal_layer)ENCODER_OPTION_FRAME_RATEfloatMaximal input frame rate, current supported range:

MAX_FRAME_RATE = 30MIN_FRAME_RATE = 1ENCODER_OPTION_BITRATEint

ENCODER_OPTION_MAX_BITRATEint

ENCODER_PADDING_PADDINGint0:disable padding;1:paddingENCODER_LTR_RECOVERY_REQUESTStructure of SLTRRecoverRequest

ENCODER_LTR_MARKING_FEEDBACKStructure of SLTRMarkingFeedback

ENCOCER_LTR_MARKING_PERIODUnsigned int

ENCODER_OPTION_LTRUnsigned int0:not enable LTR;>0 enable LTR;

LTR number is fixed to be 2 in current encoderENCODER_OPTION_ENABLE_PREFIX_NAL_ADDINGBoolfalse:not use Prefix NAL; true: use Prefix NALENCODER_OPTION_ENABLE_SPS_PPS_ID_ADDITIONBoolfalse:not adjust ID in SPS/PPS; true: adjust ID in SPS/PPSENCODER_OPTION_CURRENT_PATHstring

ENCODER_OPTION_DUMP_FILEStructure of SDumpLayerDump layer reconstruct frame to a specified fileENCODER_OPTION_TRACE_LEVELintOutput some info accoding to the trace level

Encoder Parameter List:(Note: some parameters in mentioned structure are not explained because they are to be removed)

SEncParamBase:Format

Parameter NameMeaning/ConstraintintiUsageTypeCurrently two type applications are supported.

0: camera video

1: screen content

intiInputCspcolor space of input sequencecurrently only supports videoFormatI420intiPicWidthwidth of picture in luminance samples (the maximum of all layers if multiple spatial layers presents)intiPicHeightheight of picture in luminance samples((the maximum of all layers if multiple spatial layers presents)intiTargetBitratetarget bitrate

intiRCModeRate control modefloatfMaxFrameRatemaximal input frame rate

SEncParamExt:Format

Parameter NameMeaning/ConstraintintiUsageTypeCurrently two type applications are supported.

0: camera video

1: screen contentintiInputCspcolor space of input sequencecurrently only supports videoFormatI420

intiPicWidthwidth of picture in luminance samples (the maximum of all layers if multiple spatial layers presents)intiPicHeightheight of picture in luminance samples((the maximum of all layers if multiple spatial layers presents)intiTargetBitratetarget bitrate

intiRCModeRate control modefloatfMaxFrameRatemaximal input frame rateintiTemporalLayerNumtemporal layer number, max temporal layer = 4intiSpatialLayerNumspatial layer number,

1<= iSpatialLayerNum <= MAX_SPATIAL_LAYER_NUMMAX_SPATIAL_LAYER_NUM = 4SSpatialLayerConfig

sSpatialLayers[MAX_SPATIAL_LAYER_NUM];

intiInputCspcolor space of input sequenceintiTemporalLayerNumtemporal layer number, max temporal layer = 4intiSpatialLayerNum

spatial layer number,

1<= iSpatialLayerNum <= MAX_SPATIAL_LAYER_NUMMAX_SPATIAL_LAYER_NUM = 4unsigned intuiIntraPeriodperiod of IDR frameintiNumRefFrameThe number of the reference frameUnsigned intuiFrameToBeCodedThe number of the frames to be encoded. the user doesn’t know the number or doesn’t care the number,can set 0xFFFFFFFbool

bEnableSpsPpsIdAdditionfalse:not adjust ID in SPS/PPS; true: adjust ID in SPS/PPSbool

bPrefixNalAddingCtrlfalse:not use Prefix NAL; true: use Prefix NALboolbEnableSSEIfalse:not use SSEI; true: use SSEIintiPaddingFlag0:disable padding;1:paddingintiEntropyCodingModeFlag0:CAVLC 1:CABAC.

Currently only supports nableRcFalse: don’t use rate control; true: use rate controlboolbEnableFrameSKipFalse: don’t skip frame even if VBV buffer overflow.

True: allow skipping frames to keep the bitrate within limitsintiMaxBitratethe maximum bitrate

intiMaxQpthe maximum QP encoder supports

intiMinQpThe minmum QP encoder supportsUnsigned intuiMaxNalSizeThe maximum NAL size. This value should be not 0 for dynamic slice modebool

bEnableLongTermReference;0: on, 1: offintiLTRRefNumThe number of LTR(long term reference)intiLtrMarkPeriodThe LTR marked period that is used in feedback.

Short

iMultipleThreadIdc# 0: auto(dynamic imp. internal encoder); 1: multiple threads imp. disabled; > 1: count number of threads;IntiLoopFilterDisableIdc0: on, 1: off, 2: on except for slice boundariesIntiLoopFilterAlphaC0OffsetAlphaOffset: valid range [-6, 6], default 0IntiLoopFilterBetaOffsetBetaOffset: valid range [-6, 6], default 0

bool

bEnableDenoise;denoise controlbool

bEnableBackgroundDetectionbackground detection control

bool

bEnableAdaptiveQuantadaptive quantization controlboolbEnableFrameCroppingFlag;enable cropping source pictureintbEnableSceneChangeDetectEnable scene change detection

SSpatialLayerConfigFormat

Parameter NameMeaning/ConstraintintiVideoWidthwidth of picture in luminance samples of a layerintiVideoHeightheight of picture in luminance samples of a layerfloatfFrameRateframe rate for a layerintiSpatialBitratetarget bitrate for a spatial layerintiMaxSpatialBitrate

Maximum bitrate for a spatial layerEProfileIdcuiProfileIdcvalue of profile IDC (0 for auto-detection)ELevelIdcuiLevelIdcvalue of level IDC (0 for auto-detection)Int

iDLayerQpEach layer QP for fixed quant caseSSliceConfigsSliceCfgslicing configuration

eMode0: SM_SINGLE_SLICE: SliceNum==11: SM_FIXEDSLCNUM_SLICE: according to SliceNum, Enabled dynamic slicing for multi-thread2: SM_RASTER_SLICE: according to SlicesAssign, Need input of MB numbers each slice. In addition, if other constraint in SSlicencoding may be involved.3: SM_ROWMB_SLICE: according to PictureMBHeight, a row of mbs per slice

4: SM_DYN_SLICE: according to SliceSize, Dynamic slicing (have no idea about slice_nums until encoding current frame)

sSliceCfg. sSliceArgument uiSliceMbNumUsed in uiSliceMode=2

sSliceCfg. sSliceArgument uiSliceNumUsed in uiSliceMode=1

sSliceCfg. sSliceArgument uiSliceSizeConstraintUsed in uiSliceMode=4

Encoder Return Value: CM_RETURN

Return value of parameter Initializtion: Initialize() and set option SetOption()Value

Parameter NameMeaning/Constraint0cmResultSuccessSuccessful initialized1cmInitParaErrorFound error in input parameters2cmMachPerfIsBadNot supported yet3cmUnkonwReasonNot supported yet4cmMallocMemeErrorInput source picture is NULL5

cmInitExpectedEncoder is not created correctly

Encoder Return Value: EVideoFrameType:Return value of encode one frame: EncodeFrame()Value

Parameter NameMeaning/Constraint0videoFrameTypeInvalidEncoder not ready or parameters are invalidate1videoFrameTypeIDRIDR frame in H.264

2

videoFrameTypeII frame type3videoFrameTypePP frame type4videoFrameTypeSkipEncoder decides to skip the frame, no bit stream will be ouputed5

videoFrameTypeIPMixedA frame where I and P slices are mixing, not supported yet

Decoder Usage:Step#1: create and destroy the decoderint WelsCreateDecoder(ISVCDecoder** ppDecoder);void WelsDestroyDecoder(ISVCDecoder* pDecoder);

Step#2: initialize the decodervirtual long Initialize(const SDecodingParam* pParam) = 0;

virtual long Unintialize() = 0;Step#3: invoker the decoding/*************************************************************************** * Description: * Decompress one frame or slice, and output I420 decoded data. * *Input parameters: * ParameterTYPE Description * kpSrcconst unsigned char* the h264 stream to be decoded * kiSrcLenconst int the length of h264 steam * ppDst unsigned char** buffer pointer of decoded data (YUV) * pDstInfo SBufferInfo*information provided to API including width, height, etc *pStrideint*output stride *iWidthint&output width *iHeightint&output height *

*return: if decode frame success return 0, otherwise corresponding error returned./***************************************************************************///the following API is for slice level decodingvirtual DECODING_STATE DecodeFrame2(const unsigned char* kpSrc,

const int kiSrcLen,unsigned char** ppDst,SBufferInfo* pDstInfo);

//the following API is for frame level decodingVirtual DECODING_STATE DecodeFrame(const unsigned char* kpSrc,const int kiSrcLen,unsigned char** ppDst,int* pStride,int& iWidth,int& iHeight );//Note: DecodeFrameEx() is not used.//Note: for slice level DecodeFrame2() (4 parameters input), whatever the function return value is, the outputted data of I420 f>iBufferStatus == 1,. (e.g., in multi-slice cases, only when the whole picture is completely reconstructed, this variable would be set as 1.)

Step#4: control the decodingvirtual int SetOption(DECODER_OPTION eOptionId, void* pOption) = 0;virtual int GetOption(DECODER_OPTION eOptionId, void* pOption) = 0;Decoder Option List:

Option IDInput FormatMeaning/ConstraintDECODER_OPTION_DATAFORMATintcolor format, now supports 23 only (I420)DECODER_OPTION_END_OF_STREAMboolend of stream flag

DECODER_OPTION_VCL_NALboolfeedback whether or not have VCL NAL in current AU for application layerDECODER_OPTION_TEMPORAL_IDintif have VCL NAL in current AU, then feedback the temporal IDDECODER_OPTION_FRAME_NUMintIndicate frame_numDECODER_OPTION_IDR_PIC_IDintIndicate current IDR_IDDECODER_OPTION_LTR_MARKING_FLAGboolread only, indicating if LTR_marking SE flag is used in current AUDECODER_OPTION_LTR_MARKED_FRAME_NUMintRead only, indicating the frame_num of current AU marked as LTRDECODER_OPTION_ERROR_CON_IDCintIndicate error concealment method0: disable1: frame_copy2: slice_copy (default)

Decoder Parameter List:(Note: some parameters in mentioned structure are not explained because they are to be removed)

SDecodingParam: (Note: some of the members may not be used for now.)

Format

Parameter NameMeaning/Constraintchar*pFileNameRestructedFile name of restructed frame used for PSNR calculation based debug;intiOutputColorFormatcolor space format to be outputedunsigned intuiCpuLoadCPU loadunsigned charuiTargetDqLayertarget dq layer number

unsigned charuiEcActiveFlagWhether active error concealment feature in decoderSVideoPropertysVideoPropertyVideo stream property

SVideoPropertyFormat

Parameter NameMeaning/Constraintunsigned intsizesize of structureVIDEO_BITSTREAM_TYPEeVideoBsTypeVideo stream type (AVC/SVC)

SBufferInfo:

Format

Parameter NameMeaning/ConstraintintiBufferStatus0: data not ready, 1: data readyunion UsrData

Output buffer info, see following tablesunion UsrData:

Format

Parameter NameMeaning/ConstraintSSysMEMBuffersSysMEMBufferoutput with memory, see following tablesSSysMEMBufferFormat

Parameter NameMeaning/ConstraintintiWidthwidth of decoded picintiHeightheight of decoded picintiFormattype is “EVideoFormatType”, see codec_tride[2]stride

Decoder Features----------------- Constrained Baseline Profile up to Level 5.2 (4096x2304)- Arbitrary resolution, not constrained to multiples of 16x16- Single thread for all slices- Long Term Reference (LTR) frames- Memory Management Control Operation (MMCO)- Reference picture list modification- Multiple reference frames when specified in Sequence Parameter Set (SPS)- Annex B byte stream input- YUV 4:2:0 planar output- Decoder output timing conformance- Error concealment support with slice copy as default methodOS Support----------- Windows 64-bit and 32-bit- Mac OS X 64-bit and 32-bit- Linux 64-bit and 32-bit- Android 32-bit- iOS 64-bit and 32-bit (not fully tested)Processor Support------------------ Intel x86 optionally with MMX/SSE (no AVX yet, help is welcome)- ARMv7 optionally with NEON- Any architecture using C/C++ fallback functionsTo build the arm assembly for Windows Phone, gas-preprocessor is required. It can be downloaded fromgit:/// Android Builds------------------To build for android platform, You need to install android sdk and ndk. You also need to export **ANDROID_SDK**/tools toPATH. On Linux, this can be done by'export PATH=**ANDROID_SDK**/tools:$PATH'The codec and demo can be built by'make OS=android NDKROOT=**ANDROID_NDK** TARGET= **ANDROID_TARGET**'Valid **ANDROID_TARGET** can be found in **ANDROID_SDK**/platforms, such as can also set ARCH, NDKLEVEL, GCCVERSION according to your device and NDK specifies the architecture of android device. Currently only arm and x86 are supported, the default is EL specifies android api level, the api level can be 12-19, the default is SION specifies which gcc in NDK is used, the default is 4.8.

By default these commands build for the armeabi-v7a ABI. To build for the other androidABIs, add "ARCH=mips" or "ARCH=x86". To build for the older armeabi ABI (which hasarmv5te as baseline), add "APP_ABI=armeabi" (ARCH=arm is implicit).For iOS Builds--------------You can build the libraries and demo applications using xcode project fileslocated in codec/build/iOS/dec and codec/build/iOS/ can also build the libraries (but not the demo applications) using themake based build system from the command line. Build with'make OS=ios ARCH=**ARCH**'Valid values for **ARCH** are the normal iOS architecture names such asarmv7, armv7s, arm64, and i386 and x86_64 for the simulator. Additionally,one might need to add 'SDK=X.Y' to the make command line in case the defaultSDK version isn't available. Another settable iOS specific parameteris SDK_MIN, specifying the minimum deployment target for the built other details on building using make on the command line, see'For All Platforms' Windows Builds------------------To build with gcc, add the MinGW bin directory (e.g. /c/MinGW/bin) to your path and follow the 'For All Platforms'instructions PATH="$PATH:/c/Program Files (x86)/Microsoft Visual Studio 11.0/VC/bin:/c/Program Files (x86)/MicrosoftVisual Studio 11.0/Common7/IDE"You will also need to set your INCLUDE and LIB paths to point to your VS and SDK installs. Something like this, again fromWin64 with VS2012 (note the use of Windows-style paths here).export INCLUDE="C:Program Files (x86)Microsoft Visual Studio 11.0VCinclude;C:Program Files (x86)WindowsKits8.0Includeum;C:Program Files (x86)Windows Kits8.0Includeshared"export LIB="C:Program Files (x86)Windows Kits8.0LibWin8umx86;C:Program Files (x86)Microsoft Visual Studio11.0VClib"Then add 'OS=msvc' to the make line of the 'For All Platforms' instructions.

For All Platforms-------------------From the main project directory:'make' for automatically detecting 32/64bit and building accordingly'make ENABLE64BIT=No' for 32bit builds'make ENABLE64BIT=Yes' for 64bit builds'make V=No' for a silent build (not showing the actual compiler commands)The command line programs h264enc and h264dec will appear in the main project directory.A shell script to run the command-line apps is in testbin/e information can be found in testbin/CmdLineReadMeUsing the Source----------------codec - encoder, decoder, console (test app), build (makefile, vcproj)build - scripts for Makefile build - GTest unittest n - autobuild scripts, test app config filesres - yuv and bitstream test filesLicense-------BSD, see LICENSE file for details.