/*
    WRAIFF v0.17, a tiny audiofile writing utility in C.
    $Id: wraiff.h,v 1.4 2005/05/05 03:19:45 pieter Exp $
    Latest version available at http://kmt.hku.nl/~pieter/EDU/c/wraiff/.

    Include this headerfile in your .c file (as is done in example program
    write_aiff_files.c). Also include sourcefile wraiff.c in your project or
    makefile. Thanks to Eduard Aylon and Maarten de Boer for comments.

    Copyright (c) 2004, 2005 - Pieter Suurmond

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files
    (the "Software"), to deal in the Software without restriction,
    including without limitation the rights to use, copy, modify, merge,
    publish, distribute, sublicense, and/or sell copies of the Software,
    and to permit persons to whom the Software is furnished to do so,
    subject to the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    Any person wishing to distribute modifications to the Software is
    requested to send the modifications to the original developer so that
    they can be incorporated into the canonical version.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/

    typedef struct WRAIFF* WRAIFFp;         /* Forward declaration. */
/*
    To create a new (overwrite an existing) AIFF file, call function
*/
    int WRAIFF_open(WRAIFFp*    handle,     /* Receive ptr to WRAIFF object here. */
                    const char* filename,   /* String is copied to WRAIFF object. */
                    long        samplerate, /* Number of samples per second (Hz). */
                    short       channels,   /* Number of channels (1 to 127 inc). */
                    short       bits);      /* Number of bits (8, 16 or 24).      */
/*
    It returns zero on success, non-zero on failure, as all functions in this
    WRAIFF-library do. When 0 is returned, it also leaves you a valid pointer to
    a dynamically created WRAIFF object in *handle. In all other cases, where a
    non-zero error number is returned, a NULL pointer is left in *handle.
    It tries to create or overwrite an AIFF file with the filename, samplerate,
    number of channels and number of bits that you specified. 
    After a successfull return from WRAIFF_open(), you can write audio-data to 
    the WRAIFF object by (repeatedly) calling one of the following functions:
*/
    int WRAIFF_char  (WRAIFFp ptr, const signed char*  audio, long frames);
    int WRAIFF_short (WRAIFFp ptr, const signed short* audio, long frames);
    int WRAIFF_long  (WRAIFFp ptr, const signed long*  audio, long frames);

    int WRAIFF_float (WRAIFFp ptr, const float*        audio, long frames);
    int WRAIFF_double(WRAIFFp ptr, const double*       audio, long frames);
/*
    Where argument
                   ptr = a pointer to the audiofile object.
                 audio = a pointer to array of (channel-interleaved) signed
                         chars, shorts, longs, floats or doubles.
                frames = the number of sampleframes (not samples!) to write,
                         it may be zero, but negative values yield an error. 

    On all ISO/ANSI-compilers, shorts, ints, longs and long longs are signed by
    default. A char, however, may differ per platform: on some, chars are un-
    signed by default; on others, they are signed by default. That is why the
    prototype of WRAIFF_char() explicitly uses a signed character pointer as 
    second argument.
    All these functions return zero on success, and non-zero on failure:

        1 = wrong argument(s)
        2 = sample underflow
        3 = sample overflow
        4 = write error
        5 = very large file

    Errors 2 and 3 may be ignored by the user, the library will take care of
    clipping (preventing nasty sign-swaps).

    In case of floats and doubles, the lowest audio-value that can be written
    without being clipped is always -1.0. The highest value, however, depends
    on the number of bits resolution:

         8 bits -->     127 / 128     = +0.9921875
        16 bits -->   32767 / 32768   = +0.999969482421875
        24 bits --> 8388607 / 8388608 = +0.99999988079071044921875

    In case of writing signed chars, shorts or longs, the minimum and maximum 
    sample values that you can write without being clipped are:
    
         8 bits --> min = -128;     max = +127
        16 bits --> min = -32768;   max = +32767
        24 bits --> min = -8388608; max = +8388607

    This all is simply a consequence of the 2's complement representation of 
    signed integers.

    At any time (between opening and closing) you may call
*/
    int WRAIFF_info(WRAIFFp ptr, FILE* to);
/*
    to see how many samples were written, samplerate, etc. No problem when one or
    both arguments are NULL.

    As soon as you're done, you should close / release by calling
*/
    int WRAIFF_close(WRAIFFp* handle);
/*
    Rewrites the AIFF header (the library takes care of number of sampleframes 
    written), closes the file and sets object reference *handle to NULL.
    Returns zero on success, non-zero on failure.
    That's all.
*/