minor comments
[flac.git] / src / libOggFLAC / ogg_decoder_aspect.c
1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
2  * Copyright (C) 2002,2003,2004  Josh Coalson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * - Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * - Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * - Neither the name of the Xiph.org Foundation nor the names of its
16  * contributors may be used to endorse or promote products derived from
17  * this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31
32 #include <string.h> /* for memcpy() */
33 #include "FLAC/assert.h"
34 #include "private/ogg_decoder_aspect.h"
35
36 #ifdef max
37 #undef max
38 #endif
39 #define max(x,y) ((x)>(y)?(x):(y))
40
41 /***********************************************************************
42  *
43  * Public class methods
44  *
45  ***********************************************************************/
46
47 FLAC__bool OggFLAC__ogg_decoder_aspect_init(OggFLAC__OggDecoderAspect *aspect)
48 {
49         /* we will determine the serial number later if necessary */
50         if(ogg_stream_init(&aspect->stream_state, aspect->serial_number) != 0)
51                 return false;
52
53         if(ogg_sync_init(&aspect->sync_state) != 0)
54                 return false;
55
56         aspect->need_serial_number = aspect->use_first_serial_number;
57
58         aspect->end_of_stream = false;
59         aspect->have_working_page = false;
60
61         return true;
62 }
63
64 void OggFLAC__ogg_decoder_aspect_finish(OggFLAC__OggDecoderAspect *aspect)
65 {
66         (void)ogg_sync_clear(&aspect->sync_state);
67         (void)ogg_stream_clear(&aspect->stream_state);
68 }
69
70 void OggFLAC__ogg_decoder_aspect_set_serial_number(OggFLAC__OggDecoderAspect *aspect, long value)
71 {
72         aspect->use_first_serial_number = false;
73         aspect->serial_number = value;
74 }
75
76 void OggFLAC__ogg_decoder_aspect_set_defaults(OggFLAC__OggDecoderAspect *aspect)
77 {
78         aspect->use_first_serial_number = true;
79 }
80
81 void OggFLAC__ogg_decoder_aspect_flush(OggFLAC__OggDecoderAspect *aspect)
82 {
83         OggFLAC__ogg_decoder_aspect_reset(aspect);
84 }
85
86 void OggFLAC__ogg_decoder_aspect_reset(OggFLAC__OggDecoderAspect *aspect)
87 {
88         (void)ogg_stream_reset(&aspect->stream_state);
89         (void)ogg_sync_reset(&aspect->sync_state);
90         aspect->end_of_stream = false;
91         aspect->have_working_page = false;
92 }
93
94 /*@@@@@@ needed? */
95 unsigned OggFLAC__ogg_decoder_aspect_get_unconsumed_bytes(OggFLAC__OggDecoderAspect *aspect)
96 {
97         FLAC__ASSERT(0 != aspect);
98         return aspect->sync_state.fill - aspect->sync_state.returned;
99 }
100
101 OggFLAC__OggDecoderAspectReadStatus OggFLAC__ogg_decoder_aspect_read_callback_wrapper(OggFLAC__OggDecoderAspect *aspect, FLAC__byte buffer[], unsigned *bytes, OggFLAC__OggDecoderAspectReadCallbackProxy read_callback, void *decoder, void *client_data)
102 {
103         static const unsigned OGG_BYTES_CHUNK = 8192;
104         const unsigned bytes_requested = *bytes;
105
106         /*
107          * The FLAC decoding API uses pull-based reads, whereas Ogg decoding
108          * is push-based.  In libFLAC, when you ask to decode a frame, the
109          * decoder will eventually call the read callback to supply some data,
110          * but how much it asks for depends on how much free space it has in
111          * its internal buffer.  It does not try to grow its internal buffer
112          * to accomodate a whole frame because then the internal buffer size
113          * could not be limited, which is necessary in embedded applications.
114          *
115          * Ogg however grows its internal buffer until a whole page is present;
116          * only then can you get decoded data out.  So we can't just ask for
117          * the same number of bytes from Ogg, then pass what's decoded down to
118          * libFLAC.  If what libFLAC is asking for will not contain a whole
119          * page, then we will get no data from ogg_sync_pageout(), and at the
120          * same time cannot just read more data from the client for the purpose
121          * of getting a whole decoded page because the decoded size might be
122          * larger than libFLAC's internal buffer.
123          *
124          * Instead, whenever this read callback wrapper is called, we will
125          * continually request data from the client until we have at least one
126          * page, and manage pages internally so that we can send pieces of
127          * pages down to libFLAC in such a way that we obey its size
128          * requirement.  To limit the amount of callbacks, we will always try
129          * to read in enough pages to return the full number of bytes
130          * requested.
131          */
132         *bytes = 0;
133         while (*bytes < bytes_requested && !aspect->end_of_stream) {
134                 if (aspect->have_working_page) {
135                         if (aspect->have_working_packet) {
136                                 unsigned n = bytes_requested - *bytes;
137                                 if ((unsigned)aspect->working_packet.bytes <= n) {
138                                         /* the rest of the packet will fit in the buffer */
139                                         n = aspect->working_packet.bytes;
140                                         memcpy(buffer, aspect->working_packet.packet, n);
141                                         *bytes += n;
142                                         buffer += n;
143                                         aspect->have_working_packet = false;
144                                 }
145                                 else {
146                                         /* only n bytes of the packet will fit in the buffer */
147                                         memcpy(buffer, aspect->working_packet.packet, n);
148                                         *bytes += n;
149                                         buffer += n;
150                                         aspect->working_packet.packet += n;
151                                         aspect->working_packet.bytes -= n;
152                                 }
153                         }
154                         else {
155                                 /* try and get another packet */
156                                 const int ret = ogg_stream_packetout(&aspect->stream_state, &aspect->working_packet);
157                                 if (ret > 0) {
158                                         aspect->have_working_packet = true;
159                                 }
160                                 else if (ret == 0) {
161                                         aspect->have_working_page = false;
162                                 }
163                                 else { /* ret < 0 */
164                                         /* lost sync, we'll leave the working page for the next call */
165                                         return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_LOST_SYNC;
166                                 }
167                         }
168                 }
169                 else {
170                         /* try and get another page */
171                         const int ret = ogg_sync_pageout(&aspect->sync_state, &aspect->working_page);
172                         if (ret > 0) {
173                                 /* got a page, grab the serial number if necessary */
174                                 if(aspect->need_serial_number) {
175                                         aspect->stream_state.serialno = aspect->serial_number = ogg_page_serialno(&aspect->working_page);
176                                         aspect->need_serial_number = false;
177                                 }
178                                 if(ogg_stream_pagein(&aspect->stream_state, &aspect->working_page) == 0) {
179                                         aspect->have_working_page = true;
180                                         aspect->have_working_packet = false;
181                                 }
182                                 /* else do nothing, could be a page from another stream */
183                         }
184                         else if (ret == 0) {
185                                 /* need more data */
186                                 const unsigned ogg_bytes_to_read = max(bytes_requested - *bytes, OGG_BYTES_CHUNK);
187                                 char *oggbuf = ogg_sync_buffer(&aspect->sync_state, ogg_bytes_to_read);
188
189                                 if(0 == oggbuf) {
190                                         return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_MEMORY_ALLOCATION_ERROR;
191                                 }
192                                 else {
193                                         unsigned ogg_bytes_read = ogg_bytes_to_read;
194
195                                         switch(read_callback(decoder, (FLAC__byte*)oggbuf, &ogg_bytes_read, client_data)) {
196                                                 case OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_OK:
197                                                         break;
198                                                 case OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_END_OF_STREAM:
199                                                         aspect->end_of_stream = true;
200                                                         break;
201                                                 case OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_ABORT:
202                                                         return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_ABORT;
203                                                 default:
204                                                         FLAC__ASSERT(0);
205                                         }
206
207                                         if(ogg_sync_wrote(&aspect->sync_state, ogg_bytes_read) < 0) {
208                                                 /* double protection; this will happen if the read callback returns more bytes than the max requested, which would overflow Ogg's internal buffer */
209                                                 FLAC__ASSERT(0);
210                                                 return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_ERROR;
211                                         }
212                                 }
213                         }
214                         else { /* ret < 0 */
215                                 /* lost sync, bail out */
216                                 return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_LOST_SYNC;
217                         }
218                 }
219         }
220
221         if (aspect->end_of_stream && *bytes == 0) {
222                 return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_END_OF_STREAM;
223         }
224
225         return OggFLAC__OGG_DECODER_ASPECT_READ_STATUS_OK;
226 }