From 347e4893a9ae9470bfd9fa181f579c66acd1553c Mon Sep 17 00:00:00 2001
From: huili2 <huili2@cisco.com>
Date: Mon, 24 Nov 2014 23:28:28 -0800
Subject: [PATCH] add parse only comment in API

---
 codec/api/svc/codec_api.h     | 26 +++++++++++++++++++++-----
 codec/api/svc/codec_app_def.h | 22 +++++++++++-----------
 2 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/codec/api/svc/codec_api.h b/codec/api/svc/codec_api.h
index 1e06382d..f4628d5d 100644
--- a/codec/api/svc/codec_api.h
+++ b/codec/api/svc/codec_api.h
@@ -69,7 +69,7 @@ typedef unsigned char bool;
   * @page DecoderUsageExample
   *
   * @brief
-  *   * An example for using the decoder
+  *   * An example for using the decoder for Decoding only or Parsing only
   *
   * Step 1:decoder declaration
   * @code
@@ -80,11 +80,15 @@ typedef unsigned char bool;
   *	 unsigned char *pBuf =...;
   *  //input: encoded bit stream length; should include the size of start code prefix
   *	 int iSize =...;
-  *  //output: [0~2] for Y,U,V buffer
+  *  //output: [0~2] for Y,U,V buffer for Decoding only
   *	 unsigned char *pData[3] =...;
-  *  //in-out: declare and initialize the output buffer info
+  *  //in-out: for Decoding only: declare and initialize the output buffer info, this should never co-exist with Parsing only
   *  SBufferInfo sDstBufInfo;
   *	 memset(&sDstBufInfo, 0, sizeof(SBufferInfo));
+  *  //in-out: for Parsing only: declare and initialize the output bitstream buffer info for parse only, this should never co-exist with Decoding only
+  *  SParserBsInfo sDstParseInfo;
+  *      memset(&sDstParseInfo, 0, sizeof(SParserBsInfo));
+  *      sDstParseInfo.pDstBuff = new unsigned char[PARSE_SIZE]; //In Parsing only, allocate enough buffer to save transcoded bitstream for a frame
   *
   * @endcode
   *
@@ -93,10 +97,12 @@ typedef unsigned char bool;
   *  CreateDecoder(pSvcDecoder);
   * @endcode
   *
-  *	Step 3:declare required parameter
+  *	Step 3:declare required parameter, used to differentiate Decoding only and Parsing only
   * @code
   *  SDecodingParam sDecParam = {0};
   *	 sDecParam.sVideoProperty.eVideoBsType = VIDEO_BITSTREAM_AVC;
+  *  //for Parsing only, the assignment is mandatory
+  *  sDecParam.bParseOnly = true;
   * @endcode
   *
   *	Step 4:initialize the parameter and decoder context, allocate memory
@@ -107,15 +113,25 @@ typedef unsigned char bool;
   *	Step 5:do actual decoding process in slice level;
   *        this can be done in a loop until data ends
   * @code
+  *  //for Decoding only
   *  iRet = DecodeFrame2(pBuf, iSize, pData, &sDstBufInfo);
+  *  //for Parsing only
+  *  iRet = DecodeParser(pBuf, iSize, &sDstParseInfo);
   *  //decode failed
   *	 If (iRet != 0){
   *	     RequestIDR or something like that.
   *  }
-  *  //pData can be used for render.
+  *  //for Decoding only, pData can be used for render.
   *  if (sDstBufInfo.iBufferStatus==1){
   *      output pData[0], pData[1], pData[2];
   *  }
+  * //for Parsing only, sDstParseInfo can be used for, e.g., HW decoding
+  *  if (sDstBufInfo.iBufferStatus==1){
+  *      Hardware decoding sDstParseInfo;
+  *  }
+  *  //no-delay decoding can be realized by directly calling decoder again with NULL input, as in the following. In this case, decoder would immediately reconstruct the input data. This can also be used similarly for Parsing only. Consequent decoding error and output indication should also be considered as above.
+  *  iRet = DecodeFrame2(NULL, 0, pData, &sDstBufInfo);
+  *  judge iRet, sDstBufInfo.iBufferStatus ...
   * @endcode
   *
   *	Step 6:uninitialize the decoder and memory free
diff --git a/codec/api/svc/codec_app_def.h b/codec/api/svc/codec_app_def.h
index 23a02830..4c006eec 100644
--- a/codec/api/svc/codec_app_def.h
+++ b/codec/api/svc/codec_app_def.h
@@ -459,7 +459,7 @@ typedef struct TagSVCDecodingParam {
   unsigned char	uiTargetDqLayer;       ///< setting target dq layer id
 
   ERROR_CON_IDC eEcActiveIdc;          ///< whether active error concealment feature in decoder
-  bool bParseOnly;                     ///< decoder for parse only, no reconstruction
+  bool bParseOnly;                     ///< decoder for parse only, no reconstruction. When it is true, SPS/PPS size should not exceed SPS_PPS_BS_SIZE (128). Otherwise, it will return error info
 
   SVideoProperty   sVideoProperty;    ///< video stream property
 } SDecodingParam, *PDecodingParam;
@@ -554,18 +554,18 @@ typedef struct TagDeliveryStatus {
 } SDeliveryStatus;
 
 /**
-* @brief The capability of decoder
+* @brief The capability of decoder, for SDP negotiation
 */
 typedef struct TagDecoderCapability {
-  int iProfileIdc;
-  int iProfileIop;
-  int iLevelIdc;
-  int iMaxMbps;
-  int iMaxFs;
-  int iMaxCpb;
-  int iMaxDpb;
-  int iMaxBr;
-  bool bRedPicCap;
+  int iProfileIdc;     ///< profile_idc
+  int iProfileIop;     ///< profile-iop
+  int iLevelIdc;       ///< level_idc
+  int iMaxMbps;        ///< max-mbps
+  int iMaxFs;          ///< max-fs
+  int iMaxCpb;         ///< max-cpb
+  int iMaxDpb;         ///< max-dpb
+  int iMaxBr;          ///< max-br
+  bool bRedPicCap;     ///< redundant-pic-cap
 } SDecoderCapability;
 
 /**