From cd8712d861fd4eeb5a47218b73e4298d73768c22 Mon Sep 17 00:00:00 2001 From: Martijn van Beurden Date: Wed, 18 Dec 2024 19:32:22 +0100 Subject: [PATCH] Add porting guide for 1.5.0 --- CHANGELOG.md | 2 +- include/FLAC/all.h | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d560786f15..15ecea3f4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ As there have been additions to the libFLAC interfaces, the libFLAC version numb * Built-in help and tool documentation are improved (H2Swine) * When re-encoding a FLAC file from an existing FLAC file, a check is added that the MD5 sums of both files are the same * libFLAC and libFLAC++ - * The library interfaces have been extended. See the porting guide ***TODO TODO TODO*** + * The library interfaces have been extended. See the porting guide (part of the API documentation) * An error is sent when a frame is missing * The algorithm of the 'loose mid side' option has changed. Instead of checking every few frames which option is best and keeping that for the next few frames, a fast heuristic is now used. This was necessary to enable multithreading * Most level 0 metadata interface functions now also work with Ogg FLAC files diff --git a/include/FLAC/all.h b/include/FLAC/all.h index d06dcd45bc..b85da06956 100644 --- a/include/FLAC/all.h +++ b/include/FLAC/all.h @@ -436,6 +436,50 @@ * */ +/** \defgroup porting_1_4_3_to_1_5_0 Porting from FLAC 1.4.3 to 1.5.0 + * \ingroup porting + * + * \brief + * This module describes porting from FLAC 1.4.3 to FLAC 1.5.0. + * + * \section porting_1_4_3_to_1_5_0_summary Summary + * + * Between FLAC 1.3.4 and FLAC 1.5.0, there has been changes to + * existing functions and enums: + * - the functions FLAC__metadata_get_streaminfo, + * FLAC__metadata_get_tags and FLAC__metadata_get_cuesheet can now + * read from Ogg FLAC files + * - when encoding Ogg FLAC files, the 'samples' argument of the + * write callback no longer always returns 0. + * - two error statusses have been added to the + * FLAC__StreamDecoderErrorStatus enum + * - one status is added to FLAC__StreamDecoderState, which is only + * used when the new decoding of chained streams functionality is + * enabled + * - one status is added to FLAC__StreamDecoderReadStatus, which is + * only used when the new decoding of chained streams functionality + * is enabled + * - the function + * FLAC__metadata_chain_write_with_callbacks_and_tempfile can now + * be used regardless of whether a tempfile is actually needed, + * which is useful when writing to a new file is desired anyway + * + * Furthermore, there have been the following additions: + * - the functions FLAC__stream_decoder_set_decode_chained_stream, + * FLAC__stream_decoder_get_decode_chained_stream, + * FLAC__stream_decoder_finish_link, + * FLAC__stream_decoder_skip_single_link, + * FLAC__stream_decoder_process_until_end_of_link have been added + * to support decoding of chained streams + * - the function FLAC__metadata_chain_write_new_file has been added, + * which is useful to combine copying of a file with chainging its + * metadata + * - the function FLAC__stream_decoder_find_total_samples was added, + * which seeks to the end of a file to find the total number of + * samples + * + */ + /** \defgroup flac FLAC C API * * The FLAC C API is the interface to libFLAC, a set of structures