path: root/audio_codec/libraac/aac_bitstream.h (plain)
blob: 26f2fd6887e8693f9c38797d3478f4d2bf92293b

1	/* ***** BEGIN LICENSE BLOCK *****
2	* Source last modified: $Id: aac_bitstream.h,v 1.1.1.1.2.1 2005/05/04 18:21:58 hubbe Exp $
3	*
4	* REALNETWORKS CONFIDENTIAL--NOT FOR DISTRIBUTION IN SOURCE CODE FORM
5	* Portions Copyright (c) 1995-2005 RealNetworks, Inc.
6	* All Rights Reserved.
7	*
8	* The contents of this file, and the files included with this file,
9	* are subject to the current version of the Real Format Source Code
10	* Porting and Optimization License, available at
11	* https://helixcommunity.org/2005/license/realformatsource (unless
12	* RealNetworks otherwise expressly agrees in writing that you are
13	* subject to a different license). You may also obtain the license
14	* terms directly from RealNetworks. You may not use this file except
15	* in compliance with the Real Format Source Code Porting and
16	* Optimization License. There are no redistribution rights for the
17	* source code of this file. Please see the Real Format Source Code
18	* Porting and Optimization License for the rights, obligations and
19	* limitations governing use of the contents of the file.
20	*
21	* RealNetworks is the developer of the Original Code and owns the
22	* copyrights in the portions it created.
23	*
24	* This file, and the files included with this file, is distributed and
25	* made available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND,
26	* EITHER EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS ALL
27	* SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
28	* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT
29	* OR NON-INFRINGEMENT.
30	*
31	* Technology Compatibility Kit Test Suite(s) Location:
32	* https://rarvcode-tck.helixcommunity.org
33	*
34	* Contributor(s):
35	*
36	* ***** END LICENSE BLOCK ***** */
37
38	/* bitstream reader functions. No checking for end-of-bits included! */
39
40	#ifndef _BITSTREAM_H_
41	#define _BITSTREAM_H_
42
43	#include "include/rm_memory.h"
44
45	#ifdef __cplusplus
46	extern "C" {
47	#endif
48
49	/** The bitstream structure.
50	* The idea of the bitstream reader is to keep a cache word that has the machine's
51	* largest native size. This word keeps the next-to-read bits left-aligned so that
52	* on a read, one shift suffices.
53	* The cache word is only refilled if it does not contain enough bits to satisy a
54	* a read request. Because the refill only happens in multiple of 8 bits, the maximum
55	* read size that is guaranteed to be always fulfilled is the number of bits in a long
56	* minus 8 (or the number of bits in a byte).
57	*/
58
59	struct BITSTREAM ;
60
61	/** read nBits bits from bitstream
62	* @param pBitstream the bitstream to read from
63	* @param nBits the number of bits to read. nBits must be <= 32, currently.
64	* @return the bits read, right-justified
65	*/
66	unsigned int readBits(struct BITSTREAM *pBitstream, int nBits) ;
67
68	/** push bits back into the bitstream.
69	* This call is here to make look-ahead possible, where after reading the client
70	* may realize it has read too far ahead. It is guaranteed to succeed as long as
71	* you don't push more bits back than have been read in the last readBits() call.
72	* @param pBitstream the bitstream to push back into
73	* @param bits the bits to push back
74	* @param nBits the number of bits to push back.
75	* @return an error code, signalling success or failure.
76	*/
77	int unreadBits(struct BITSTREAM *pBitstream, int bits, int nBits) ;
78
79	/** byte-align the bitstream read pointer. */
80	void byteAlign(struct BITSTREAM *pBitstream) ;
81
82	/** allocate memory for a new bitstream structure.
83	* @param ppBitstream a pointer to a bitstream handle, to be initialized on
84	* successfull return
85	* @param nBits the maximum number of bits this bitstream must be able to hold.
86	* nBits must be divisible by 32.
87	* @param pUserMem optional user-defined memory handle
88	* @param fpMalloc user-defined malloc() implementation
89	* @return an error code, signalling success or failure.
90	* @see reverseBitstream
91	*/
92	int newBitstream(struct BITSTREAM **ppBitstream, int nBits,
93	void* pUserMem, rm_malloc_func_ptr fpMalloc) ;
94
95	/** free memory associated with a bitstream structure.
96	* @param pBitstream a bitstream handle
97	* @param pUserMem optional user-defined memory handle
98	* @param fpFree user-defined free() implementation
99	*/
100	void deleteBitstream(struct BITSTREAM *pBitstream, void *pUserMem,
101	rm_free_func_ptr fpFree) ;
102
103	/** feed nbits bits to the bitstream, byte-wise.
104	* @param pBitstream the bitstream into which to feed the bytes
105	* @param input the input from which to read the bytes
106	* @param nbits the number of bits in the input. nbits must be divisible by 32
107	* for reverseBitstream() to work.
108	* @return an error code, signalling success or failure.
109	* @see reverseBitstream
110	*/
111
112	int feedBitstream(struct BITSTREAM *pBitstream, const unsigned char *input, int nbits) ;
113
114	/** set bitstream position, relative to origin defined through feedBitstream().
115	* @param pBitstream the bitstream
116	* @param position the position in bits (must be multiple of 8, currently).
117	* Always measured from beginning, regardless of direction.
118	* @param direction the direction of reading (+1/-1)
119	*/
120
121	int setAtBitstream(struct BITSTREAM *pBitstream, int position, int direction) ;
122
123	/** return the number of bits left until end-of-stream.
124	* @param pBitstream the bitstream
125	* @return the number of bits left
126	*/
127	int bitsLeftInBitstream(struct BITSTREAM *pBitstream) ;
128
129	#ifdef __cplusplus
130	}
131	#endif
132
133	#endif /* _BITSTREAM_H_ */
134