/***************************************************************************
 *     Copyright (c) 2005, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: bvlc.h $
 * $brcm_Revision: 4 $
 * $brcm_Date: 9/1/05 3:36p $
 *
 * Module Description: Converts startcode index to bcmplayer index
 *
 * Revision History:
 *
 * $brcm_Log: /BSEAV/lib/utils/bvlc.h $
 * 
 * 4   9/1/05 3:36p erickson
 * PR16964: added const to parameter
 * 
 * 3   7/8/05 10:05a erickson
 * PR16155: modified b_vlc_decode to require current_index instead of
 * always starting from data[0]. This makes keeping track of where you
 * are in the buffer much easier for the application. Also changed and
 * expanded the examples.
 * 
 * 2   4/6/05 5:17p erickson
 * PR14708: use bstd.h if at all possible for maximum portability
 * 
 * 1   3/21/05 3:43p erickson
 * PR14451: added generic vlc decode algorithm
 * 
 ************************************************************/
#ifndef BVLC_H__
#define BVLC_H__

#ifndef USE_LEGACY_KERNAL_INTERFACE
#include "bstd.h"
#else
#include <stdint.h>
#endif

/*=*************************************
bvlc is a set of Broadcom VLC decode algorithms.

Examples:
	unsigned char data[size];
	int next_index, next_bit;
	
	// Decode 3 contiguous vlc values
	val1 = b_vlc_decode(data, size, 0, 7, &next_index, &next_bit);
	val2 = b_vlc_decode(data, size, next_index, next_bit, &next_index, &next_bit
	val3 = b_vlc_decode(data, size, next_index, next_bit, NULL, NULL);
	
	// Decode the 4th vlc value
	b_vlc_skip(data, size, 0, 7, &next_index, &next_bit);
	b_vlc_skip(data, size, next_index, next_bit, &next_index, &next_bit);
	b_vlc_skip(data, size, next_index, next_bit, &next_index, &next_bit);
	val = b_vlc_decode(data, size, next_index, next_bit, NULL, NULL);

	// Decode a vlc value which is an index of the subsequent VLC value to decode.
	val = b_vlc_decode(data, size, 0, 7, &next_index, &next_bit);
	while (val--)
		b_vlc_skip(data, size, next_index, next_bit, &next_index, &next_bit);
	val = b_vlc_decode(data, size, next_index, next_bit, NULL, NULL);
********************************************/

/**
Summary:
Decodes a VLC value in a byte stream.

Description:

Return Value:
Returns a VLC decoded value if >= 0. 
If -1 there was a VLC decode failure.
**/
int b_vlc_decode(
	const uint8_t *data, 			/* [size_is(size)] Array of bytes which contain a vlc encoded value */
	unsigned size, 			/* Size of data */
	unsigned current_index,	/* The starting index the data array. */
	unsigned current_bit, 	/* The bit in data[current_index] where the vlc decode should start.
								vlc decode proceeds from MSB to LSB, so the first
								bit will be 7. */
	unsigned *next_index, /* [out] the index in data which should be used for an
								adjacent vlc decode. Can be NULL. */
	unsigned *next_bit		/* [out] the bit in data[index] which should be used for an 
								adjacent vlc decode. Can be NULL. */
	);


/**
This works by short circuiting the VLC decode algorithm in order to skip
over a VLC encoded value.

Return Value:
0 if successfully skipped. next_index and next_bit are updated.
If -1 there was a VLC decode failure.
**/
int b_vlc_skip(
	const uint8_t *data,			/* [size_is(size)] see b_vlc_decode */
	unsigned size,			/* see b_vlc_decode */
	unsigned current_index,	/* see b_vlc_decode */
	unsigned current_bit, 	/* see b_vlc_decode */
	unsigned *next_index,	/* [out] the index in data which should be used for an 
								adjacent vlc decode. Required. */
	unsigned *next_bit		/* [out] the bit in data[index] which should be used for an 
								adjacent vlc decode. Required. */
	);

#endif