packet_buffer.h revision 14b43beb7ce4440b30dcea31196de5b4a529cb6b 
1/*
2 *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11/*
12 * Interface for the actual packet buffer data structure.
13 */
14
15#ifndef PACKET_BUFFER_H
16#define PACKET_BUFFER_H
17
18#include "typedefs.h"
19
20#include "webrtc_neteq.h"
21#include "rtp.h"
22
23/* Define minimum allowed buffer memory, in 16-bit words */
24#define PBUFFER_MIN_MEMORY_SIZE	150
25
26/****************************/
27/* The packet buffer struct */
28/****************************/
29
30typedef struct
31{
32
33    /* Variables common to the entire buffer */
34    WebRtc_UWord16 packSizeSamples; /* packet size in samples of last decoded packet */
35    WebRtc_Word16 *startPayloadMemory; /* pointer to the payload memory */
36    int memorySizeW16; /* the size (in WebRtc_Word16) of the payload memory */
37    WebRtc_Word16 *currentMemoryPos; /* The memory position to insert next payload */
38    int numPacketsInBuffer; /* The number of packets in the buffer */
39    int insertPosition; /* The position to insert next packet */
40    int maxInsertPositions; /* Maximum number of packets allowed */
41
42    /* Arrays with one entry per packet slot */
43    /* NOTE: If these are changed, the changes must be accounted for at the end of
44     the function WebRtcNetEQ_GetDefaultCodecSettings(). */
45    WebRtc_UWord32 *timeStamp; /* Timestamp in slot n */
46    WebRtc_Word16 **payloadLocation; /* Memory location of payload in slot n */
47    WebRtc_UWord16 *seqNumber; /* Sequence number in slot n */
48    WebRtc_Word16 *payloadType; /* Payload type of packet in slot n */
49    WebRtc_Word16 *payloadLengthBytes; /* Payload length of packet in slot n */
50    WebRtc_Word16 *rcuPlCntr; /* zero for non-RCU payload, 1 for main payload
51     2 for redundant payload */
52    int *waitingTime;
53
54
55    /* Statistics counter */
56    WebRtc_UWord16 discardedPackets; /* Number of discarded packets */
57
58} PacketBuf_t;
59
60/*************************/
61/* Function declarations */
62/*************************/
63
64/****************************************************************************
65 * WebRtcNetEQ_PacketBufferInit(...)
66 *
67 * This function initializes the packet buffer.
68 *
69 * Input:
70 *		- bufferInst	: Buffer instance to be initialized
71 *		- noOfPackets	: Maximum number of packets that buffer should hold
72 *		- memory		: Pointer to the storage memory for the payloads
73 *		- memorySize	: The size of the payload memory (in WebRtc_Word16)
74 *
75 * Output:
76 *      - bufferInst    : Updated buffer instance
77 *
78 * Return value			:  0 - Ok
79 *						  <0 - Error
80 */
81
82int WebRtcNetEQ_PacketBufferInit(PacketBuf_t *bufferInst, int maxNoOfPackets,
83                                 WebRtc_Word16 *pw16_memory, int memorySize);
84
85/****************************************************************************
86 * WebRtcNetEQ_PacketBufferFlush(...)
87 *
88 * This function flushes all the packets in the buffer.
89 *
90 * Input:
91 *		- bufferInst	: Buffer instance to be flushed
92 *
93 * Output:
94 *      - bufferInst    : Flushed buffer instance
95 *
96 * Return value			:  0 - Ok
97 */
98
99int WebRtcNetEQ_PacketBufferFlush(PacketBuf_t *bufferInst);
100
101/****************************************************************************
102 * WebRtcNetEQ_PacketBufferInsert(...)
103 *
104 * This function inserts an RTP packet into the packet buffer.
105 *
106 * Input:
107 *		- bufferInst	: Buffer instance
108 *		- RTPpacket		: An RTP packet struct (with payload, sequence
109 *						  number, etc.)
110 *
111 * Output:
112 *      - bufferInst    : Updated buffer instance
113 *		- flushed		: 1 if buffer was flushed, 0 otherwise
114 *
115 * Return value			:  0 - Ok
116 *						  -1 - Error
117 */
118
119int WebRtcNetEQ_PacketBufferInsert(PacketBuf_t *bufferInst, const RTPPacket_t *RTPpacket,
120                                   WebRtc_Word16 *flushed);
121
122/****************************************************************************
123 * WebRtcNetEQ_PacketBufferExtract(...)
124 *
125 * This function extracts a payload from the buffer.
126 *
127 * Input:
128 *		- bufferInst	: Buffer instance
129 *		- bufferPosition: Position of the packet that should be extracted
130 *
131 * Output:
132 *		- RTPpacket		: An RTP packet struct (with payload, sequence
133 *						  number, etc)
134 *      - bufferInst    : Updated buffer instance
135 *
136 * Return value			:  0 - Ok
137 *						  <0 - Error
138 */
139
140int WebRtcNetEQ_PacketBufferExtract(PacketBuf_t *bufferInst, RTPPacket_t *RTPpacket,
141                                    int bufferPosition, int *waitingTime);
142
143/****************************************************************************
144 * WebRtcNetEQ_PacketBufferFindLowestTimestamp(...)
145 *
146 * This function finds the next packet with the lowest timestamp.
147 *
148 * Input:
149 *       - buffer_inst        : Buffer instance.
150 *       - current_time_stamp : The timestamp to compare packet timestamps with.
151 *       - erase_old_packets  : If non-zero, erase packets older than currentTS.
152 *
153 * Output:
154 *       - time_stamp         : Lowest timestamp that was found.
155 *       - buffer_position    : Position of this packet (-1 if there are no
156 *                              packets in the buffer).
157 *       - payload_type       : Payload type of the found payload.
158 *
159 * Return value               :  0 - Ok;
160 *                             < 0 - Error.
161 */
162
163int WebRtcNetEQ_PacketBufferFindLowestTimestamp(PacketBuf_t* buffer_inst,
164                                                uint32_t current_time_stamp,
165                                                uint32_t* time_stamp,
166                                                int* buffer_position,
167                                                int erase_old_packets,
168                                                int16_t* payload_type);
169
170/****************************************************************************
171 * WebRtcNetEQ_PacketBufferGetSize(...)
172 *
173 * Calculate and return an estimate of the total data length (in samples)
174 * currently in the buffer. The estimate is calculated as the number of
175 * packets currently in the buffer (which does not have any remaining waiting
176 * time), multiplied with the number of samples obtained from the last
177 * decoded packet.
178 *
179 * Input:
180 *		- bufferInst	: Buffer instance
181 *
182 * Return value			: The buffer size in samples
183 */
184
185WebRtc_Word32 WebRtcNetEQ_PacketBufferGetSize(const PacketBuf_t *bufferInst);
186
187/****************************************************************************
188 * WebRtcNetEQ_IncrementWaitingTimes(...)
189 *
190 * Increment the waiting time for all packets in the buffer by one.
191 *
192 * Input:
193 *    - bufferInst  : Buffer instance
194 *
195 * Return value     : n/a
196 */
197
198void WebRtcNetEQ_IncrementWaitingTimes(PacketBuf_t *buffer_inst);
199
200/****************************************************************************
201 * WebRtcNetEQ_GetDefaultCodecSettings(...)
202 *
203 * Calculates a recommended buffer size for a specific set of codecs.
204 *
205 * Input:
206 *		- codecID	    : An array of codec types that will be used
207 *      - noOfCodecs    : Number of codecs in array codecID
208 *
209 * Output:
210 *		- maxBytes	    : Recommended buffer memory size in bytes
211 *      - maxSlots      : Recommended number of slots in buffer
212 *
213 * Return value			:  0 - Ok
214 *						  <0 - Error
215 */
216
217int WebRtcNetEQ_GetDefaultCodecSettings(const enum WebRtcNetEQDecoder *codecID,
218                                        int noOfCodecs, int *maxBytes, int *maxSlots);
219
220#endif /* PACKET_BUFFER_H */
221