skl_mpg4.h

mpeg4编解码器

          @see SKL_MEM_I */
    virtual SKL_MEM_I *Set_Memory_Manager(SKL_MEM_I *Mem=0) = 0;

      /** Sets the CPU feature to use.
          @param Cpu : see the enum description for a list of available 
          cpu features. */
    virtual void Set_CPU(SKL_CPU_FEATURE Cpu = SKL_CPU_DETECT) = 0;

      /** Sets the custom quantization matrix for MPEG4 quantization type (0).
          @param Intra Should be 1 to use the custom matrix for intra macroblocks, or 0
          for inter macroblocks.
          @param M a pointer to 64 bytes containing the 8x8 matrix coefficients. If
          the pointer is null, the coefficients are restored to their default, initial,
          values. */
    virtual void Set_Custom_Matrix(int Intra, const SKL_BYTE *M=0) = 0;

      /** This function plugs a new analyzer code in replacement of
          the previous one. 
          @return Set_Analyzer() returns previous analyzer.
          @param Analyzer Should be 0 to restore the default, built-in, analyzer.
          @see Get_analyzer
          @see SKL_MP4_ANALYZER */
    virtual SKL_MP4_ANALYZER *Set_Analyzer(SKL_MP4_ANALYZER *Analyzer=0) = 0;

      /** Returns the analyzer currently associated with the encoder. 
          @see Set_analyzer */
    virtual SKL_MP4_ANALYZER *Get_Analyzer() const = 0;

       /** Set post-coding hook function. The signature of this function
           is the following typedef: <p>
           typedef void (*SKL_MP4_SLICER)(const SKL_MP4_PIC *Pic, int y, int Height, SKL_ANY Data);
           @param Slicer callback function to use
           @param Slicer_Data can be anything, and will be passed as is
           to the Slicer hook function. */
    virtual void Set_Slicer(SKL_MP4_SLICER Slicer, SKL_ANY Slicer_Data=0) = 0;

      /** @internal 
          For debug only. Returns all the Y/U/V planes in a single, edged, frame 
          @param Pic the structure filled with frame's pixels  */
    virtual void Get_All_Frames(SKL_MP4_PIC *Pic) const = 0;

      /** @internal Sets the internal debug level. */
    virtual void Set_Debug_Level(int Level=0) = 0;

     /** This method can be used for very special syntax controls over the bitstream.
        @param Param can be one of the following constant strings:<br>
        <ul>
        <li>"emit-key-headers": for streaming purpose, the bitstream will contain
        a VOL header every time a keyframe is transmitted.<br></li>
        <li>"no-emit-key-headers": disables the above (default).<br></li>
        <li>"emit-sequence-codes": the bitstream will contain a SEQUENCE_START and
        SEQUENCE_END codes at the beginning and the end.<br></li>
        <li>"no-sequence-codes": disables the above (default).<br></li>
        </ul>
        Note: Call to this method should occur preferably at the beginning of
        the encoding process.
       */
    virtual int Ioctl(SKL_CST_STRING Param) = 0;
};


//////////////////////////////////////////////////////////
//  SKL_MP4_ANALYZER
// Frame analyzers to be plugged into SKL_MP4_ENC
//////////////////////////////////////////////////////////

  /** @struct SKL_MP4_INFOS 
      SKL_MP4_INFOS is used to share informations between
      the bitstream-coding core (instance of SKL_MP4_ENC)
      and the frame analyzer (instance of SKL_MP4_ANALYZER)
    */
struct SKL_MP4_INFOS
{
  SKL_MP4_INFOS(SKL_MEM_I *Memory=0);

  SKL_MEM_I *Mem;                                   /**< Memory pool */
  SKL_MEM_I *Set_Memory_Manager(SKL_MEM_I *mem);    /**< mem=0 => use C++ heap */

    /** public infos of general interest */

  int Width;             /**< Width of picture, in pixel. */
  int Height;            /**< Height of picture, in pixel. */
  int BpS;               /**< Bytes Per Scanline */
  int Frame_Number;      /**< Frame number in display order. */

  int MB_W;              /**< Width of padded picture, in macroblock units */
  int MB_H;              /**< Height of padded picture, in macroblock units */
  int MV_Stride;         /**< stride for motion vectors array */

  int Texture_Bits;
  int MV_Bits;
  int Coded_Bits;

  SKL_MP4_PIC *Past;     /**< The past picture use for reference */
  SKL_MP4_PIC *Cur;      /**< The current picture being motion-searched */
  SKL_MP4_PIC *Future;   /**< The future reference picture, if applicable (B-VOP). */

  const SKL_IMG_DSP *Img_Dsp;   /**< Image low-level DSP functions */
  const SKL_MB_DSP  *MB_Dsp;    /**< Macroblock low-level DSP functions */
  SKL_GMC_DSP       *GMC_Dsp;   /**< GMC low-level DSP functions */
};

  /** @class SKL_MP4_ANALYZER
      Base class for analyzing input, making coding decisions
      and performing bit-rate control. Actually drives
      the bitstream-coder (SKL_MP4_ENC). 
      Setting/Access/Control of internal parameter is granted 
      through the Set_Param() and Get_Param() functions.
      See description of this function for details. We encourage you
      to have a look at the example 'tmp4.cpp', that exercises every
      possible params of Set_Param() through the command-line options.

      @see SKL_MP4_ENC
    */
class SKL_MP4_ANALYZER
{
  protected:

    SKL_MEM_I *_Mem;       /**< @internal Memory pool, for allocating auxiliary data, e.g. */

  public:

    SKL_MP4_ANALYZER(SKL_MEM_I *Mem=0) : _Mem(Mem) {}
    virtual ~SKL_MP4_ANALYZER() {}


      /** This function is called when the invoked analyzer is about to be enabled. */
    virtual void Wake_Up(SKL_MP4_ANALYZER *Previous) = 0;
      /** this function is called when the invoked analyzer is about to be disabled. */
    virtual void Shut_Down() = 0;

      /** This function is responsible for motion estimation.
          It should populate the array of motion
          vectors MVs[] and the macroblock map *Map with the
          desired macroblock types.

          @return
          return code: 0: intra coding required (I-VOP)
                       1/2: predictive coding required (1=P or 2=B-VOP)
                       3: GMC coding requested
       */
    virtual int Analyze(SKL_MP4_INFOS * const Frame) = 0;

      /** This function handles variable per-macroblocks quantization.

          New->Map[].dQ should be filled with dQ hints. 
          This is a separate virtual, not merged with the above Analyze() 
          motion estimation, since the coding type can be changed by the
          encoder inbetween. This impacts the range of allowed dQ 
          values (eg.: for B-VOP).
        */
    virtual void Analyze_dQ(SKL_MP4_INFOS * const Frame, int For_BVOP) = 0;


      /** Post-coding update (for rate control, e.g.)
          @param Infos contains informations about the last coded frame
       */
    virtual void Post_Coding_Update(const SKL_MP4_INFOS * const Infos) = 0;

      /** Sets the value of the integer parameter described by Param string.
          These parameter settings control the core of the codec during
          motion estimation and bitstream coding.
          @return 0 if parameter is not applicable, or -1 if Value has invalid range.
          @param Param can be one of the following constant strings:<br>

          <ul>
          <li>"buffer-size": If non-zero, specify the size of coded bits buffer to allocate for each frame coding.<br></li>

          <li>"quant": Sets the main quantizer (the lower, the higher the quality). 
          Should be in range [1..31]. When variable bitrate is used, this value is 
          internally adjusted after each frame coding, while trying to meet the
          desired bitrate.<br></li>
          <li>"base-quant": Similar to "quant" parameter, but sets the quantizer of key-frames. 
          By default, key-frames are assumed to share the global quantizer, if this parameter
          is not set.<br></li>
          <li>"quant-type": Quantization method used: 0 for H263's, 1 for MPEG4's.<br></li>

          <li>"hi-mem": Consumes more memory for faster motion search. Only useful for Quarter Pixel.</li>

          <li>"intra-limit": Percentage of INTRA macroblock necessary to trigger a scene 
          change (with key frame signaled).<br></li>
          <li>"intra-max-delay": Maximum allowed number of P-frames between each INTRA key-frame.<br></li>
          <li>"intra-max-count": Counter for "intra-max-delay". When it reaches 0, an INTRA frame is emitted.<br></li>

          <li>"rounding": Block-interpolation rounding mode: 0 (down) or 1 (up)<br></li>
          <li>"subpixel": Subpixel precision to use: 0=full-pixel, 1=half-pixel (default), 2=quarter pixel.<br></li>
          <li>"use-trellis": Switch trellis-based quantization on (non-zero Value) or off (Value=0)<br></li>

          <li>"search-size": size in 16-pixels units of the search window. When
          bitrate control is on, this size is changed adaptively.<br></li>
          <li>"base-search-size": Similar to "search-size", this is the default value
          used as starting point after each key-frame.<br></li>

          <li>"search-method": Internal searcho method (0 to 5)<br></li>
          <li>"search-metric": Metric for evaluating match: 0=SAD (default), 1=SSD, 2=Hadamard.<br></li>

          <li>"4v-probing": Worthiness Threshold (as percentage) of 4-motion-vector blocks to probe.<br></li>

          <li>"sad-skip-limit": Metric threshold below which a block is SKIPed <br></li>
          <li>"sad-intra-limit": Metric threshold above which a block is coded INTRA<br></li>
          <li>"inter-threshold": Amplitude of INTER coefficient below which a sub-block is skipped (using Coded Block Pattern)<br></li>

          <li>"bitrate": If non-zero, turns (simplistic) bitrate control on. It then will adjust "quant", "search-size"
          parameter, and use the "framerate" setting too.<br></li>

          <li>"field-pred-probing": Worthiness Threshold (as percentage) for field/frame block decision.<br></li>
          <li>"interlace-field": Use interlace-block coding if non-zero<br></li>
          <li>"interlace-dct": Use interlace-block DCT coding of coefficient, if non-zero<br></li>

          <li>"gmc-pts": Number of GMC points to use (0 to 3)<br></li>
          <li>"gmc-mode": If non-zero, turns GMC estimation on (experimental)<br></li>
          <li>"gmc-accuracy": GMC interpolation precision (0 to 3)<br></li>

          <li>"reduced-frame": Use reduced-frame coding, if non-zero<br></li>
          <li>"luminance-masking": Switch luminance-masking on (non-zero Value) or off (Value=0)<br></li>

          <li>"frequency": Frequency of frame-tick resets.<br></li>
          <li>"frame-ticks": Precision of frame-tick coding<br></li>

          </ul>
          @param Value the parameter value to set.

          Note: call to Set_Param() can occur any time during the encoding process
          and will take effect immediately during next call to Encode(). In particular,
          this method can be used during two-pass encoding to restore modified parameters
          stored in a first-pass file.
        */
    virtual int Set_Param(const char * const Param, int Value) = 0;

      /** Sets the value of the float parameter described by Param string.
          These parameter settings control the core of the codec during
          motion estimation and bitstream coding. 
          @return 0 if parameter is not applicable, or -1 if Value has invalid range.
          @param Param can be one of the following constant strings:<br>

          <ul>
          <li>"dquant-amp": If non-zero, turns luminance-masking on, with the specified Amplitude (the higher, the higher the effect, and the lower the quality).<br></li>
          <li>"framerate": Number of frame-per-seconds to achieve when bit-rate control is on.<br></li>
          <li>"quant": Specify the quantizer as a float value.<br></li>
          <li>"base-quant": Specify the base quantizer as a float value.<br></li>
          <li>"search-size": Specify the search-window size as a float value.<br></li>
          <li>"base-search-size":Specify the base search-window size as a float value.<br></li>
          </ul>

          Note: call to Set_Param() can occur any time during the encoding process
          and will take effect immediately during next call to Encode(). In particular,
          this method can be used during two-pass encoding to restore modified parameters
          stored in a first-pass file.
          @param Value the parameter value to set.
        */
    virtual int Set_Param(const char * const Param, float Value) = 0;

      /** Sets the value of the string parameter described by Param string.
          @return 0 if parameter is not applicable, or -1 if Value has invalid range.
          @param Param can be one of the following constant strings:<br>

          <ul>
          <li>"passfile": Name of log file to use for 2-pass bitrate control. This parameter
          should be set before encoding process begins.<br></li>
          </ul>

          @param Value the string parameter value to set.
        */
    virtual int Set_Param(const char * const Param, const char * const Value) = 0;

      /** Returns the current value of the integer parameter described by Param string.
          @return 0 if parameter is not applicable.
          @see Set_Param()
          @param Value
          @param Param This string can be one of the corresponding ones passed to Set_Param().
          In addition, there are some non-settable parameters, whose values can be
          accessed using the following string:
          <ul>
          <li>"fcode": Desired typical length of motion vectors (bitstream syntax).<br></li>
          <li>"version": the version of the core (analyzer)<br></li>
          </ul>
          @param Value pointer the parameter value.
        */
    virtual int Get_Param(const char * const Param, int *Value) const = 0;

      /** Returns the current value of the float parameter described by Param string.
          @return 0 if parameter is not applicable.
          @see Set_Param()
          @param Param: This string can be one of the corresponding ones passed to Set_Param().
          @param Value pointer the parameter value.
        */
    virtual int Get_Param(const char * const Param, float *Value) const = 0;

      /** Returns the current value of the string parameter described by Param string.
          @return 0 if parameter is not applicable.
          @see Set_Param()
          @param Param: This string can be one of the corresponding ones passed to Set_Param().
          @param Value pointer the parameter value.
        */
    virtual int Get_Param(const char * const Param, const char ** const Value) const = 0;

      /** Get read-only internal data. Returns NULL is not applicable. This
          is mainly for internal use. */
    virtual const int *Get_Param(const char * const Param) const = 0;

      /** Set a new memory pool to use internally for subsequent memory allocation.
          Warning: it should preferably be called at start-up only, 
          to ensure that cycles of New()/Delete() are performed on the
          same memory pool.
          @param Mem The memory pool to use. If equal to 0 (default),
          the C++ heap will be used. 
          @return This function will return the previous memory manager.
          @see SKL_MEM_I 
          @see Get_Mem() */
    virtual SKL_MEM_I *Set_Memory_Manager(SKL_MEM_I *Mem=0) = 0;
      /** This function returns the current memory pool, as set by
        Set_Memory_Manager()
        @see Get_Memory_Manager()
        @see SKL_MEM_I  */
    SKL_MEM_I *Get_Mem() const { return _Mem; }

     /** @internal prints analyzer's capabilities.  */
    virtual void Print_Caps() = 0;
};

  /** factory for default Analyzer. Note that it is already assigned by default
      to each SKL_MP4_ENC instances. You need not set another one. */
extern SKL_EXPORT SKL_MP4_ANALYZER *Skl_MP4_Get_Default_Analyzer(SKL_MEM_I *Mem);

  /** Destructor of default analyzer.
      @param Analyzer Must be an instance returned by Skl_MP4_Get_Default_Analyzer */
extern SKL_EXPORT void Skl_MP4_Destroy_Default_Analyzer(SKL_MP4_ANALYZER *Analyzer);

//////////////////////////////////////////////////////////

#endif   /* _SKL_MPG4_H_ */