comparison ivi_common.h @ 12181:0885e7a93ed4 libavcodec

Fix Doxygen @param command attribute syntax. The [in] and [out] attributes have to be appended to the @param command.

12180:b24153464669

/**
 *  Generate a huffman codebook from the given descriptor
 *  and convert it into the FFmpeg VLC table.
 *
 *  @param cb   [in]  pointer to codebook descriptor
 *  @param vlc  [out] where to place the generated VLC table
 *  @param flag [in]  flag: 1 - for static or 0 for dynamic tables
 *  @return     result code: 0 - OK, -1 = error (invalid codebook descriptor)
 */
int  ff_ivi_create_huff_from_desc(const IVIHuffDesc *cb, VLC *vlc, int flag);

/**

/**
 *  Decode a huffman codebook descriptor from the bitstream
 *  and select specified huffman table.
 *
 *  @param gb           [in,out] the GetBit context
 *  @param desc_coded   [in] flag signalling if table descriptor was coded
 *  @param which_tab    [in] codebook purpose (IVI_MB_HUFF or IVI_BLK_HUFF)
 *  @param huff_tab     [out] pointer to the descriptor of the selected table
 *  @param avctx        [in] AVCodecContext pointer
 *  @return             zero on success, negative value otherwise
 */
int  ff_ivi_dec_huff_desc(GetBitContext *gb, int desc_coded, int which_tab,
                          IVIHuffTab *huff_tab, AVCodecContext *avctx);

/**
 *  Compare two huffman codebook descriptors.
 *
 *  @param desc1    [in] ptr to the 1st descriptor to compare
 *  @param desc2    [in] ptr to the 2nd descriptor to compare
 *  @return         comparison result: 0 - equal, 1 - not equal
 */
int  ff_ivi_huff_desc_cmp(const IVIHuffDesc *desc1, const IVIHuffDesc *desc2);

/**
 *  Copy huffman codebook descriptors.
 *
 *  @param dst  [out] ptr to the destination descriptor
 *  @param src  [in]  ptr to the source descriptor
 */
void ff_ivi_huff_desc_copy(IVIHuffDesc *dst, const IVIHuffDesc *src);

/**
 *  Initialize planes (prepares descriptors, allocates buffers etc).
 *
 *  @param planes       [in,out] pointer to the array of the plane descriptors
 *  @param cfg          [in] pointer to the ivi_pic_config structure describing picture layout
 *  @return             result code: 0 - OK
 */
int  ff_ivi_init_planes(IVIPlaneDesc *planes, const IVIPicConfig *cfg);

/**
 *  Free planes, bands and macroblocks buffers.
 *
 *  @param planes       [in] pointer to the array of the plane descriptors
 */
void ff_ivi_free_buffers(IVIPlaneDesc *planes);

/**
 *  Initialize tile and macroblock descriptors.
 *
 *  @param planes       [in,out] pointer to the array of the plane descriptors
 *  @param tile_width   [in]     tile width
 *  @param tile_height  [in]     tile height
 *  @return             result code: 0 - OK
 */
int  ff_ivi_init_tiles(IVIPlaneDesc *planes, int tile_width, int tile_height);

/**

 *  The size is stored as a variable-length field having the following format:
 *  if (tile_data_size < 255) than this field is only one byte long
 *  if (tile_data_size >= 255) than this field four is byte long: 0xFF X1 X2 X3
 *  where X1-X3 is size of the tile data
 *
 *  @param gb   [in,out] the GetBit context
 *  @return     size of the tile data in bytes
 */
int  ff_ivi_dec_tile_data_size(GetBitContext *gb);

/**
 *  Decode block data:
 *  extract huffman-coded transform coefficients from the bitstream,
 *  dequantize them, apply inverse transform and motion compensation
 *  in order to reconstruct the picture.
 *
 *  @param gb   [in,out] the GetBit context
 *  @param band [in]     pointer to the band descriptor
 *  @param tile [in]     pointer to the tile descriptor
 *  @return     result code: 0 - OK, -1 = error (corrupted blocks data)
 */
int  ff_ivi_decode_blocks(GetBitContext *gb, IVIBandDesc *band, IVITile *tile);

/**
 *  Handle empty tiles by performing data copying and motion
 *  compensation respectively.
 *
 *  @param avctx    [in] ptr to the AVCodecContext
 *  @param band     [in] pointer to the band descriptor
 *  @param tile     [in] pointer to the tile descriptor
 *  @param mv_scale [in] scaling factor for motion vectors
 */
void ff_ivi_process_empty_tile(AVCodecContext *avctx, IVIBandDesc *band,
                               IVITile *tile, int32_t mv_scale);

/**
 *  Convert and output the current plane.
 *  This conversion is done by adding back the bias value of 128
 *  (subtracted in the encoder) and clipping the result.
 *
 *  @param plane        [in]  pointer to the descriptor of the plane being processed
 *  @param dst          [out] pointer to the buffer receiving converted pixels
 *  @param dst_pitch    [in]  pitch for moving to the next y line
 */
void ff_ivi_output_plane(IVIPlaneDesc *plane, uint8_t *dst, int dst_pitch);

#if IVI_DEBUG
/**

12181:0885e7a93ed4

/**
 *  Generate a huffman codebook from the given descriptor
 *  and convert it into the FFmpeg VLC table.
 *
 *  @param[in]   cb    pointer to codebook descriptor
 *  @param[out]  vlc   where to place the generated VLC table
 *  @param[in]   flag  flag: 1 - for static or 0 for dynamic tables
 *  @return     result code: 0 - OK, -1 = error (invalid codebook descriptor)
 */
int  ff_ivi_create_huff_from_desc(const IVIHuffDesc *cb, VLC *vlc, int flag);

/**

/**
 *  Decode a huffman codebook descriptor from the bitstream
 *  and select specified huffman table.
 *
 *  @param[in,out]  gb          the GetBit context
 *  @param[in]      desc_coded  flag signalling if table descriptor was coded
 *  @param[in]      which_tab   codebook purpose (IVI_MB_HUFF or IVI_BLK_HUFF)
 *  @param[out]     huff_tab    pointer to the descriptor of the selected table
 *  @param[in]      avctx       AVCodecContext pointer
 *  @return             zero on success, negative value otherwise
 */
int  ff_ivi_dec_huff_desc(GetBitContext *gb, int desc_coded, int which_tab,
                          IVIHuffTab *huff_tab, AVCodecContext *avctx);

/**
 *  Compare two huffman codebook descriptors.
 *
 *  @param[in]  desc1  ptr to the 1st descriptor to compare
 *  @param[in]  desc2  ptr to the 2nd descriptor to compare
 *  @return         comparison result: 0 - equal, 1 - not equal
 */
int  ff_ivi_huff_desc_cmp(const IVIHuffDesc *desc1, const IVIHuffDesc *desc2);

/**
 *  Copy huffman codebook descriptors.
 *
 *  @param[out]  dst  ptr to the destination descriptor
 *  @param[in]   src  ptr to the source descriptor
 */
void ff_ivi_huff_desc_copy(IVIHuffDesc *dst, const IVIHuffDesc *src);

/**
 *  Initialize planes (prepares descriptors, allocates buffers etc).
 *
 *  @param[in,out]  planes  pointer to the array of the plane descriptors
 *  @param[in]      cfg     pointer to the ivi_pic_config structure describing picture layout
 *  @return             result code: 0 - OK
 */
int  ff_ivi_init_planes(IVIPlaneDesc *planes, const IVIPicConfig *cfg);

/**
 *  Free planes, bands and macroblocks buffers.
 *
 *  @param[in]  planes  pointer to the array of the plane descriptors
 */
void ff_ivi_free_buffers(IVIPlaneDesc *planes);

/**
 *  Initialize tile and macroblock descriptors.
 *
 *  @param[in,out]  planes       pointer to the array of the plane descriptors
 *  @param[in]      tile_width   tile width
 *  @param[in]      tile_height  tile height
 *  @return             result code: 0 - OK
 */
int  ff_ivi_init_tiles(IVIPlaneDesc *planes, int tile_width, int tile_height);

/**

 *  The size is stored as a variable-length field having the following format:
 *  if (tile_data_size < 255) than this field is only one byte long
 *  if (tile_data_size >= 255) than this field four is byte long: 0xFF X1 X2 X3
 *  where X1-X3 is size of the tile data
 *
 *  @param[in,out]  gb  the GetBit context
 *  @return     size of the tile data in bytes
 */
int  ff_ivi_dec_tile_data_size(GetBitContext *gb);

/**
 *  Decode block data:
 *  extract huffman-coded transform coefficients from the bitstream,
 *  dequantize them, apply inverse transform and motion compensation
 *  in order to reconstruct the picture.
 *
 *  @param[in,out]  gb    the GetBit context
 *  @param[in]      band  pointer to the band descriptor
 *  @param[in]      tile  pointer to the tile descriptor
 *  @return     result code: 0 - OK, -1 = error (corrupted blocks data)
 */
int  ff_ivi_decode_blocks(GetBitContext *gb, IVIBandDesc *band, IVITile *tile);

/**
 *  Handle empty tiles by performing data copying and motion
 *  compensation respectively.
 *
 *  @param[in]  avctx     ptr to the AVCodecContext
 *  @param[in]  band      pointer to the band descriptor
 *  @param[in]  tile      pointer to the tile descriptor
 *  @param[in]  mv_scale  scaling factor for motion vectors
 */
void ff_ivi_process_empty_tile(AVCodecContext *avctx, IVIBandDesc *band,
                               IVITile *tile, int32_t mv_scale);

/**
 *  Convert and output the current plane.
 *  This conversion is done by adding back the bias value of 128
 *  (subtracted in the encoder) and clipping the result.
 *
 *  @param[in]   plane      pointer to the descriptor of the plane being processed
 *  @param[out]  dst        pointer to the buffer receiving converted pixels
 *  @param[in]   dst_pitch  pitch for moving to the next y line
 */
void ff_ivi_output_plane(IVIPlaneDesc *plane, uint8_t *dst, int dst_pitch);

#if IVI_DEBUG
/**