replace the compile time ordinals.h.in->ordinals.h conversion with a static ordinals.h
[flac.git] / include / FLAC++ / encoder.h
1 /* libFLAC++ - Free Lossless Audio Codec library
2  * Copyright (C) 2002,2003  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 #ifndef FLACPP__ENCODER_H
33 #define FLACPP__ENCODER_H
34
35 #include "export.h"
36
37 #include "FLAC/file_encoder.h"
38 #include "FLAC/seekable_stream_encoder.h"
39 #include "FLAC/stream_encoder.h"
40 #include "decoder.h"
41
42
43 /** \file include/FLAC++/encoder.h
44  *
45  *  \brief
46  *  This module contains the classes which implement the various
47  *  encoders.
48  *
49  *  See the detailed documentation in the
50  *  \link flacpp_encoder encoder \endlink module.
51  */
52
53 /** \defgroup flacpp_encoder FLAC++/encoder.h: encoder classes
54  *  \ingroup flacpp
55  *
56  *  \brief
57  *  This module describes the three encoder layers provided by libFLAC++.
58  *
59  * The libFLAC++ encoder classes are object wrappers around their
60  * counterparts in libFLAC.  All three encoding layers available in
61  * libFLAC are also provided here.  The interface is very similar;
62  * make sure to read the \link flac_encoder libFLAC encoder module \endlink.
63  *
64  * The only real difference here is that instead of passing in C function
65  * pointers for callbacks, you inherit from the encoder class and provide
66  * implementations for the callbacks in the derived class; because of this
67  * there is no need for a 'client_data' property.
68  */
69
70 namespace FLAC {
71         namespace Encoder {
72
73                 // ============================================================
74                 //
75                 //  Equivalent: FLAC__StreamEncoder
76                 //
77                 // ============================================================
78
79                 /** \defgroup flacpp_stream_encoder FLAC++/encoder.h: stream encoder class
80                  *  \ingroup flacpp_encoder
81                  *
82                  *  \brief
83                  *  This class wraps the ::FLAC__StreamEncoder.
84                  *
85                  * See the \link flac_stream_encoder libFLAC stream encoder module \endlink.
86                  *
87                  * \{
88                  */
89
90                 /** This class wraps the ::FLAC__StreamEncoder.
91                  */
92                 class FLACPP_API Stream {
93                 public:
94                         class FLACPP_API State {
95                         public:
96                                 inline State(::FLAC__StreamEncoderState state): state_(state) { }
97                                 inline operator ::FLAC__StreamEncoderState() const { return state_; }
98                                 inline const char *as_cstring() const { return ::FLAC__StreamEncoderStateString[state_]; }
99                                 const char *resolved_as_cstring(const Stream &) const;
100                         protected:
101                                 ::FLAC__StreamEncoderState state_;
102                         };
103
104                         Stream();
105                         virtual ~Stream();
106
107                         bool is_valid() const;
108                         inline operator bool() const { return is_valid(); }
109
110                         bool set_verify(bool value);
111                         bool set_streamable_subset(bool value);
112                         bool set_do_mid_side_stereo(bool value);
113                         bool set_loose_mid_side_stereo(bool value);
114                         bool set_channels(unsigned value);
115                         bool set_bits_per_sample(unsigned value);
116                         bool set_sample_rate(unsigned value);
117                         bool set_blocksize(unsigned value);
118                         bool set_max_lpc_order(unsigned value);
119                         bool set_qlp_coeff_precision(unsigned value);
120                         bool set_do_qlp_coeff_prec_search(bool value);
121                         bool set_do_escape_coding(bool value);
122                         bool set_do_exhaustive_model_search(bool value);
123                         bool set_min_residual_partition_order(unsigned value);
124                         bool set_max_residual_partition_order(unsigned value);
125                         bool set_rice_parameter_search_dist(unsigned value);
126                         bool set_total_samples_estimate(FLAC__uint64 value);
127                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
128
129                         State    get_state() const;
130                         Decoder::Stream::State get_verify_decoder_state() const;
131                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
132                         bool     get_verify() const;
133                         bool     get_streamable_subset() const;
134                         bool     get_do_mid_side_stereo() const;
135                         bool     get_loose_mid_side_stereo() const;
136                         unsigned get_channels() const;
137                         unsigned get_bits_per_sample() const;
138                         unsigned get_sample_rate() const;
139                         unsigned get_blocksize() const;
140                         unsigned get_max_lpc_order() const;
141                         unsigned get_qlp_coeff_precision() const;
142                         bool     get_do_qlp_coeff_prec_search() const;
143                         bool     get_do_escape_coding() const;
144                         bool     get_do_exhaustive_model_search() const;
145                         unsigned get_min_residual_partition_order() const;
146                         unsigned get_max_residual_partition_order() const;
147                         unsigned get_rice_parameter_search_dist() const;
148                         FLAC__uint64 get_total_samples_estimate() const;
149
150                         State init();
151
152                         void finish();
153
154                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
155                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
156                 protected:
157                         virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
158                         virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
159
160                         ::FLAC__StreamEncoder *encoder_;
161                 private:
162                         static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
163                         static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
164
165                         // Private and undefined so you can't use them:
166                         Stream(const Stream &);
167                         void operator=(const Stream &);
168                 };
169
170                 /* \} */
171
172                 /** \defgroup flacpp_seekable_stream_encoder FLAC++/encoder.h: seekable stream encoder class
173                  *  \ingroup flacpp_encoder
174                  *
175                  *  \brief
176                  *  This class wraps the ::FLAC__SeekableStreamEncoder.
177                  *
178                  * See the \link flac_seekable_stream_encoder libFLAC seekable stream encoder module \endlink.
179                  *
180                  * \{
181                  */
182
183                 /** This class wraps the ::FLAC__SeekableStreamEncoder.
184                  */
185                 class FLACPP_API SeekableStream {
186                 public:
187                         class FLACPP_API State {
188                         public:
189                                 inline State(::FLAC__SeekableStreamEncoderState state): state_(state) { }
190                                 inline operator ::FLAC__SeekableStreamEncoderState() const { return state_; }
191                                 inline const char *as_cstring() const { return ::FLAC__SeekableStreamEncoderStateString[state_]; }
192                                 const char *resolved_as_cstring(const SeekableStream &) const;
193                         protected:
194                                 ::FLAC__SeekableStreamEncoderState state_;
195                         };
196
197                         SeekableStream();
198                         virtual ~SeekableStream();
199
200                         bool is_valid() const;
201                         inline operator bool() const { return is_valid(); }
202
203                         bool set_verify(bool value);
204                         bool set_streamable_subset(bool value);
205                         bool set_do_mid_side_stereo(bool value);
206                         bool set_loose_mid_side_stereo(bool value);
207                         bool set_channels(unsigned value);
208                         bool set_bits_per_sample(unsigned value);
209                         bool set_sample_rate(unsigned value);
210                         bool set_blocksize(unsigned value);
211                         bool set_max_lpc_order(unsigned value);
212                         bool set_qlp_coeff_precision(unsigned value);
213                         bool set_do_qlp_coeff_prec_search(bool value);
214                         bool set_do_escape_coding(bool value);
215                         bool set_do_exhaustive_model_search(bool value);
216                         bool set_min_residual_partition_order(unsigned value);
217                         bool set_max_residual_partition_order(unsigned value);
218                         bool set_rice_parameter_search_dist(unsigned value);
219                         bool set_total_samples_estimate(FLAC__uint64 value);
220                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
221
222                         State    get_state() const;
223                         Stream::State get_stream_encoder_state() const;
224                         Decoder::Stream::State get_verify_decoder_state() const;
225                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
226                         bool     get_verify() const;
227                         bool     get_streamable_subset() const;
228                         bool     get_do_mid_side_stereo() const;
229                         bool     get_loose_mid_side_stereo() const;
230                         unsigned get_channels() const;
231                         unsigned get_bits_per_sample() const;
232                         unsigned get_sample_rate() const;
233                         unsigned get_blocksize() const;
234                         unsigned get_max_lpc_order() const;
235                         unsigned get_qlp_coeff_precision() const;
236                         bool     get_do_qlp_coeff_prec_search() const;
237                         bool     get_do_escape_coding() const;
238                         bool     get_do_exhaustive_model_search() const;
239                         unsigned get_min_residual_partition_order() const;
240                         unsigned get_max_residual_partition_order() const;
241                         unsigned get_rice_parameter_search_dist() const;
242                         FLAC__uint64 get_total_samples_estimate() const;
243
244                         State init();
245
246                         void finish();
247
248                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
249                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
250                 protected:
251                         virtual ::FLAC__SeekableStreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
252                         virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
253
254                         ::FLAC__SeekableStreamEncoder *encoder_;
255                 private:
256                         static ::FLAC__SeekableStreamEncoderSeekStatus seek_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
257                         static ::FLAC__StreamEncoderWriteStatus write_callback_(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
258
259                         // Private and undefined so you can't use them:
260                         SeekableStream(const SeekableStream &);
261                         void operator=(const SeekableStream &);
262                 };
263
264                 /* \} */
265
266                 /** \defgroup flacpp_file_encoder FLAC++/encoder.h: file encoder class
267                  *  \ingroup flacpp_encoder
268                  *
269                  *  \brief
270                  *  This class wraps the ::FLAC__FileEncoder.
271                  *
272                  * See the \link flac_file_encoder libFLAC file encoder module \endlink.
273                  *
274                  * \{
275                  */
276
277                 /** This class wraps the ::FLAC__FileEncoder.
278                  */
279                 class FLACPP_API File {
280                 public:
281                         class FLACPP_API State {
282                         public:
283                                 inline State(::FLAC__FileEncoderState state): state_(state) { }
284                                 inline operator ::FLAC__FileEncoderState() const { return state_; }
285                                 inline const char *as_cstring() const { return ::FLAC__FileEncoderStateString[state_]; }
286                                 const char *resolved_as_cstring(const File &) const;
287                         protected:
288                                 ::FLAC__FileEncoderState state_;
289                         };
290
291                         File();
292                         virtual ~File();
293
294                         bool is_valid() const;
295                         inline operator bool() const { return is_valid(); }
296
297                         bool set_verify(bool value);
298                         bool set_streamable_subset(bool value);
299                         bool set_do_mid_side_stereo(bool value);
300                         bool set_loose_mid_side_stereo(bool value);
301                         bool set_channels(unsigned value);
302                         bool set_bits_per_sample(unsigned value);
303                         bool set_sample_rate(unsigned value);
304                         bool set_blocksize(unsigned value);
305                         bool set_max_lpc_order(unsigned value);
306                         bool set_qlp_coeff_precision(unsigned value);
307                         bool set_do_qlp_coeff_prec_search(bool value);
308                         bool set_do_escape_coding(bool value);
309                         bool set_do_exhaustive_model_search(bool value);
310                         bool set_min_residual_partition_order(unsigned value);
311                         bool set_max_residual_partition_order(unsigned value);
312                         bool set_rice_parameter_search_dist(unsigned value);
313                         bool set_total_samples_estimate(FLAC__uint64 value);
314                         bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
315                         bool set_filename(const char *value);
316
317                         State    get_state() const;
318                         SeekableStream::State get_seekable_stream_encoder_state() const;
319                         Stream::State get_stream_encoder_state() const;
320                         Decoder::Stream::State get_verify_decoder_state() const;
321                         void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
322                         bool     get_verify() const;
323                         bool     get_streamable_subset() const;
324                         bool     get_do_mid_side_stereo() const;
325                         bool     get_loose_mid_side_stereo() const;
326                         unsigned get_channels() const;
327                         unsigned get_bits_per_sample() const;
328                         unsigned get_sample_rate() const;
329                         unsigned get_blocksize() const;
330                         unsigned get_max_lpc_order() const;
331                         unsigned get_qlp_coeff_precision() const;
332                         bool     get_do_qlp_coeff_prec_search() const;
333                         bool     get_do_escape_coding() const;
334                         bool     get_do_exhaustive_model_search() const;
335                         unsigned get_min_residual_partition_order() const;
336                         unsigned get_max_residual_partition_order() const;
337                         unsigned get_rice_parameter_search_dist() const;
338                         FLAC__uint64 get_total_samples_estimate() const;
339
340                         State init();
341
342                         void finish();
343
344                         bool process(const FLAC__int32 * const buffer[], unsigned samples);
345                         bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
346                 protected:
347                         virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
348
349                         ::FLAC__FileEncoder *encoder_;
350                 private:
351                         static void progress_callback_(const ::FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
352
353                         // Private and undefined so you can't use them:
354                         File(const Stream &);
355                         void operator=(const Stream &);
356                 };
357
358                 /* \} */
359
360         };
361 };
362
363 #endif