Changeset 390 for libmpc/trunk/include


Ignore:
Timestamp:
04/05/08 20:09:57 (17 years ago)
Author:
r2d
Message:

libmpcdec API cleanup and documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • libmpc/trunk/include/mpc/mpcdec.h

    r384 r390  
    7171void mpc_decoder_exit(mpc_decoder *p_dec);
    7272
    73 /// Call this next after calling mpc_decoder_setup.
    74 /// \param si streaminfo structure indicating format of source stream
    75 /// \param fast_seeking boolean 0 = use fast seeking if safe, 1 = force fast seeking
    76 // void mpc_decoder_set_seeking(mpc_decoder *p_dec, mpc_streaminfo *si, mpc_bool_t fast_seeking);
     73/**
     74 * Sets decoder sample scaling factor.  All decoded samples will be multiplied
     75 * by this factor. Useful for applying replay gain.
     76 * @param scale_factor multiplicative scaling factor
     77 */
     78void mpc_decoder_scale_output(mpc_decoder *p_dec, double scale_factor);
     79
     80void mpc_decoder_decode_frame(mpc_decoder * d, mpc_bits_reader * r, mpc_frame_info * i);
     81
     82// This is the gain reference used in old replaygain
     83#define MPC_OLD_GAIN_REF 64.82
    7784
    7885/**
    79  * set the scf indexes for seeking use
    80  * needed only for sv7 seeking
    81  * @param d
     86 * init demuxer
     87 * @param p_reader initialized mpc_reader pointer
     88 * @return an initialized mpc_demux pointer
    8289 */
    83 void mpc_decoder_reset_scf(mpc_decoder * d, int value);
     90mpc_demux * mpc_demux_init(mpc_reader * p_reader);
     91/// free demuxer
     92void mpc_demux_exit(mpc_demux * d);
     93/**
     94 * Calls mpc_decoder_scale_output to set the scaling factor according to the
     95 * replay gain stream information and the supplied ouput level
     96 * @param d pointer to a musepack demuxer
     97 * @param level the desired ouput level (in db). Must be MPC_OLD_GAIN_REF (64.82 db) if you want to get the old replaygain behavior
     98 * @param use_gain set it to MPC_TRUE if you want to set the scaling factor according to the stream gain
     99 * @param use_title MPC_TRUE : uses the title gain, MPC_FALSE : uses the album gain
     100 * @param clip_prevention MPC_TRUE : uses cliping prevention
     101 */
     102void mpc_set_replay_level(mpc_demux * d, float level, mpc_bool_t use_gain,
     103                          mpc_bool_t use_title, mpc_bool_t clip_prevention);
     104/// decode frame
     105mpc_status mpc_demux_decode(mpc_demux * d, mpc_frame_info * i);
     106/// get streaminfo
     107void mpc_demux_get_info(mpc_demux * d, mpc_streaminfo * i);
     108/// seeks to a given sample
     109mpc_status mpc_demux_seek_sample(mpc_demux * d, mpc_uint64_t destsample);
     110/// seeks to a given second
     111mpc_status mpc_demux_seek_second(mpc_demux * d, double seconds);
    84112
    85 /// Sets decoder sample scaling factor.  All decoded samples will be multiplied
    86 /// by this factor.
    87 /// \param scale_factor multiplicative scaling factor
    88 void mpc_decoder_scale_output(mpc_decoder *p_dec, double scale_factor);
     113/// \return the current position in the stream (in bits) from the beginning of the file
     114mpc_seek_t mpc_demux_pos(mpc_demux * d);
    89115
    90 void mpc_set_replay_level(mpc_demux * d, float level, mpc_bool_t use_gain,
    91                                                   mpc_bool_t use_title, mpc_bool_t clip_prevention);
    92 
    93 /// Actually reads data from previously initialized stream.  Call
    94 /// this iteratively to decode the mpc stream.
    95 /// \param buffer destination buffer for decoded samples
    96 /// \param vbr_update_acc \todo document me
    97 /// \param vbr_update_bits \todo document me
    98 /// \return -1 if an error is encountered
    99 /// \return 0 if the stream has been completely decoded successfully and there are no more samples
    100 /// \return > 0 to indicate the number of bytes that were actually read from the stream.
    101 void mpc_decoder_decode_frame(mpc_decoder * d, mpc_bits_reader * r, mpc_frame_info * i);
    102 
    103 // init demuxer
    104 mpc_demux * mpc_demux_init(mpc_reader * p_reader);
    105 // free demuxer
    106 void mpc_demux_exit(mpc_demux * d);
    107 // decode frame
    108 mpc_status mpc_demux_decode(mpc_demux * d, mpc_frame_info * i);
    109 // get streaminfo
    110 void mpc_demux_get_info(mpc_demux * d, mpc_streaminfo * i);
    111 // seek
    112 mpc_status mpc_demux_seek_sample(mpc_demux * d, mpc_uint64_t destsample);
    113 mpc_status mpc_demux_seek_second(mpc_demux * d, double seconds);
    114 mpc_seek_t mpc_demux_pos(mpc_demux * d);
    115 // chapters
     116/// chapters : only for sv8 streams
     117/**
     118 * Gets the number of chapters in the stream
     119 * @param d pointer to a musepack demuxer
     120 * @return the number of chapters found in the stream
     121 */
    116122mpc_int_t mpc_demux_chap_nb(mpc_demux * d);
     123/**
     124 * Gets datas associated to a given chapter
     125 * You can pass 0 for tag and tag_size if you don't needs the tag information
     126 * The chapter tag is an APEv2 tag without the preamble
     127 * @param d pointer to a musepack demuxer
     128 * @param chap_nb chapter number you want datas (from 0 to mpc_demux_chap_nb(d) - 1)
     129 * @param tag will return a pointer to the chapter tag datas
     130 * @param tag_size will be filed with the tag data size (0 if no tag for this chapter)
     131 * @return the sample where the chapter starts
     132 */
    117133mpc_uint64_t mpc_demux_chap(mpc_demux * d, int chap_nb, char ** tag, mpc_uint_t * tag_size);
    118 
    119134
    120135#ifdef __cplusplus
Note: See TracChangeset for help on using the changeset viewer.