From a70054d7474f413c086fc94095b839aa96d68dbd Mon Sep 17 00:00:00 2001 From: Josh Coalson Date: Sat, 11 Jan 2003 06:24:09 +0000 Subject: [PATCH] write up some missing documentation --- include/FLAC/format.h | 84 +++++++++++++----------- include/FLAC/metadata.h | 140 ++++++++++++++++++++++++++++++++++++---- 2 files changed, 173 insertions(+), 51 deletions(-) diff --git a/include/FLAC/format.h b/include/FLAC/format.h index fdc95c18..271c6a4b 100644 --- a/include/FLAC/format.h +++ b/include/FLAC/format.h @@ -588,24 +588,18 @@ typedef struct { extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */ -/** XXX. (c.f. format specification) +/** FLAC CUESHEET track index structure. (See the + * format specification for + * the full description of each field.) */ typedef struct { FLAC__uint64 offset; - /**< The index offset from the beginning of the track, in samples. - * For CD-DA, the offset must be evenly divisible by 588 samples (588 - * samples = 44100 samples/sec * 1/75th of a sec). Note that the - * offset is from the beginning of the track, not the beginning of - * the audio data. + /**< Offset in samples, relative to the track offset, of the index + * point. */ FLAC__byte number; - /**< The index number. For CD-DA, an index number of 0 corresponds - * to the track pregap. There must be at least one index in every - * track except the lead-out track. The first index in a track must - * be 0 or 1 and subsequently index numbers must increase by 1. Index - * numbers must be unique within a track. - */ + /**< The index point number. */ } FLAC__StreamMetadata_CueSheet_Index; extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */ @@ -613,35 +607,32 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == @@@@3*8 (bits) */ -/** XXX. (c.f. format specification) +/** FLAC CUESHEET track structure. (See the + * format specification for + * the full description of each field.) */ typedef struct { FLAC__uint64 offset; - /**< The track offset from the beginning of the audio data, in samples. - * This track offset is the offset to the first index point of the - * track. Note that for CD-DA, the track's offset in the TOC is that - * of the track's INDEX 01 even if there is an INDEX 00. - * - * For CD-DA, the offset must be evenly divisible by 588 samples (588 - * samples = 44100 samples/sec * 1/75th of a sec). - */ + /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */ FLAC__byte number; - /**< The track number. A track number of 0 is not allowed to avoid - * conflicting with the CD-DA spec, which reserves this for the - * lead-in. For CD-DA the number must be 1-99, or 170 for the lead-out. - * It is not required but encouraged to start with track 1 and increase - * sequentially. A CUESHEET block is required to have a lead-out - * track; it is always the last track in the cuesheet and the number - * must be 170 for CD-DA. Track numbers must be unique within a - * CUESHEET. - */ + /**< The track number. */ + + char isrc[13]; + /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing '\0' */ + + unsigned type:1; + /**< The track type: 0 for audio, 1 for non-audio. */ + + unsigned pre_emphasis:1; + /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */ - char isrc[13]; /*@@@@ 12 ascii characters plus trailing '\0' */ - unsigned type:1; /*@@@@q-channel control bit 3: 0=>audio, 1=>data (undefined for CD-DA, defined for CDROM) */ - unsigned pre_emphasis:1; /*@@@@q-channel control bit 5: 0=>no pre-em, 1=>pre-em */ FLAC__byte num_indices; + /**< The number of track index points. */ + FLAC__StreamMetadata_CueSheet_Index *indices; + /**< NULL if num_indices == 0, else pointer to array of index points. */ + } FLAC__StreamMetadata_CueSheet_Track; extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */ @@ -653,14 +644,29 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */ -/** FLAC CUESHEET structure. (c.f. format specification) +/** FLAC CUESHEET structure. (See the + * format specification + * for the full description of each field.) */ typedef struct { - char media_catalog_number[129]; /*@@@@ in the stream, the media_catalog_number will be 128 alphanumeric ascii characters; unused digits are padded out to the right with NUL characters. in memory, the 129th character will be guaranteed to be a null character so that the whole string is always a valid C string. CD-DA: 13 ascii digits ('0'-'9') plus 116 trailing '\0' characters */ - FLAC__uint64 lead_in; /*@@@@ length of lead-in in samples; required to compute some versions of CD TOC hashes; CD-DA says the lead-in must be digital silence and rippers don't save it by convention, so TRACK 00 is disallowed and instead we store only the length. The lead-in is the number of samples up to the first index point of the first track, \b not INDEX 01 of the first track. This is so applications can correctly compute a CD-DA TOC equivalent even when there is TRACK 01 INDEX 00 data. */ - FLAC__bool is_cd; /* \c true if CUESHEET corresponds to a Compact Disc, else \c false */ + char media_catalog_number[129]; + /**< Media catalog number, in ASCII printable characters 0x20-0x7e. In + * general, the media catalog number may be 0 to 128 bytes long; any + * unused characters should be right-padded with NUL characters. + */ + + FLAC__uint64 lead_in; + /**< The number of lead-in samples. */ + + FLAC__bool is_cd; + /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false */ + unsigned num_tracks; + /**< The number of tracks. */ + FLAC__StreamMetadata_CueSheet_Track *tracks; + /**< NULL if num_tracks == 0, else pointer to array of tracks. */ + } FLAC__StreamMetadata_CueSheet; extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */ @@ -670,7 +676,9 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */ -/** Structure that is used when a metadata block of unknown type is loaded. The contents are opaque. +/** Structure that is used when a metadata block of unknown type is loaded. + * The contents are opaque. The structure is used only internally to + * correctly handle unknown metadata. */ typedef struct { FLAC__byte *data; diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index 5afbfeb7..ee010b33 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -1172,6 +1172,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__ */ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments); +/*@@@@ code and docs need to assert on track_num */ /** Sets a comment in a VORBIS_COMMENT block. * * If \a copy is \c true, a copy of the entry is stored; otherwise, the object @@ -1217,10 +1218,6 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__Stream FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); /** Delete a comment in a VORBIS_COMMENT block at the given index. - * - * If \a copy is \c true, a copy of the entry is stored; otherwise, the object - * takes ownership of the \c entry->entry pointer. Returns \c false if - * \a copy == \c true and malloc fails. * * \param object A pointer to an existing VORBIS_COMMENT object. * \param comment_num The index of the comment to delete. @@ -1310,30 +1307,147 @@ FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_C /*@@@@ document */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices); -/*@@@@ document */ +/** Insert an index point in a CUESHEET track at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index of the track to modify. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param index_num The index into the track's index array at which to + * insert the index point. NOTE: this is not necessarily + * the same as the index point's \a number field. The + * indices at and after \a index_num move right one + * position. To append an index point to the end, set + * \a index_num to + * \c object->data.cue_sheet.tracks[track_num].num_indices . + * \param index The index point to insert. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks >= track_num \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode + * \retval FLAC__bool + * \c false if realloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index); /*@@@@ document, add to unit tests */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); -/*@@@@ document */ +/** Delete an index point in a CUESHEET track at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index into the track array of the track to + * modify. NOTE: this is not necessarily the same + * as the track's \a number field. + * \param index_num The index into the track's index array of the index + * to delete. NOTE: this is not necessarily the same + * as the index's \a number field. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode + * \retval FLAC__bool + * \c false if realloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); -/*@@@@ document */ +/** Resize the track array. + * + * If the size shrinks, elements will truncated; if it grows, new blank + * tracks will be added to the end. + * + * \param object A pointer to an existing CUESHEET object. + * \param new_num_tracks The desired length of the array; may be \c 0. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || + * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks); -/*@@@@ document */ -/*@@@@ you may safely un-const the \a track pointer if \a copy is \c true */ +/*@@@@ code and docs need to assert on track_num */ +/** Sets a track in a CUESHEET block. + * + * If \a copy is \c true, a copy of the track is stored; otherwise, the object + * takes ownership of the \a track pointer. Returns \c false if + * \a copy == \c true and malloc fails. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num Index into track array to set. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param track The track to set the track to. You may safely pass in + * a const pointer if \a copy is \c true. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); -/*@@@@ document */ -/*@@@@ you may safely un-const the \a track pointer if \a copy is \c true */ +/** Insert a track in a CUESHEET block at the given index. + * + * If \a copy is \c true, a copy of the track is stored; otherwise, the object + * takes ownership of the \a track pointer. Returns \c false if + * \a copy == \c true and malloc fails. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index at which to insert the track. NOTE: this + * is not necessarily the same as the track's \a number + * field. The tracks at and after \a track_num move right + * one position. To append a track to the end, set + * \a track_num to \c object->data.cue_sheet.num_tracks . + * \param track The track to insert. You may safely pass in a const + * pointer if \a copy is \c true. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks >= track_num \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); -/*@@@@ document, add to unit tests */ +/*@@@@ add to unit tests */ +/** Insert a blank track in a CUESHEET block at the given index. + * + * A blank track is one in which all field values are zero. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index at which to insert the track. NOTE: this + * is not necessarily the same as the track's \a number + * field. The tracks at and after \a track_num move right + * one position. To append a track to the end, set + * \a track_num to \c object->data.cue_sheet.num_tracks . + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks >= track_num \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num); -/*@@@@ document */ +/** Delete a track in a CUESHEET block at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index into the track array of the track to + * delete. NOTE: this is not necessarily the same + * as the track's \a number field. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \retval FLAC__bool + * \c false if realloc fails, else \c true. + */ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num); /** Check a cue sheet to see if it conforms to the FLAC specification.