afNewFileSetup(3dm)                                        afNewFileSetup(3dm)


NAME
     afNewFileSetup - create and initialize an AFfilesetup structure

SYNOPSIS
     #include <dmedia/audiofile.h>

     AFfilesetup afNewFileSetup(void)

RETURNED VALUE
     An opaque AFfilesetup structure initialized to the default configuration
     for a new audio file opened with write access, or for opening a raw
     (headerless) audio file for read access.

DESCRIPTION
     Use afNewFileSetup() to create and initialize an AFfilesetup structure.

     This structure passes configuration parameters to afOpenFile(3dm), which
     formats the skeleton for a new file accordingly.

     When an AFfilesetup structure is no longer needed it should be discarded
     with afFreeFileSetup(3dm).  Freeing an AFfilesetup will not affect any
     open AFfilehandle structure.

     Configuration parameters include:

     -   the desired audio file format

     -   the number of audio tracks and the type of sample data stored in each

     -   the number of markers allocated for each track

     -   the number of instrument configurations (including loop points)

     -   the number of loops allocated for each instrument

     -   the number, types, and sizes of miscellaneous data chunks (strings,
         etc)

     -   integer ID's for tracks, instruments, markers, loops, miscellaneous
         data

     For AIFF-C (and AIFF) files, the above list of parameters simplifies a
     bit.  There is always one audio track per file.  There is at most one
     instrument configuration per file, and there are  always two loops per
     instrument.

     To initialize the various file configuration parameters stored in an
     AFfilesetup structure, see the initialization routines mentioned below in
     SEE ALSO.


DEFAULT FILE SETUP CONFIGURATION
     The default parameter values in a new AFfilesetup structure are listed
     here.
     - file format
          defaults to AIFF-C, denoted by the constant AF_FILE_AIFFC

     - default audio track
          one track per file,  with track ID AF_DEFAULT_TRACK

     - markers for audio track
          four markers with ID's {1,2,3,4}

     - interleaved channels for audio track
          2 (stereo)

     - sample format for audio track
          two's complement 16-bit linear PCM, given by the constant
          AF_SAMPFMT_TWOSCOMP with width 16

     - compression used on audio track
          no compression, specified by the constant AF_COMPRESSION_NONE

     - default instrument configuration
          one instrument configuration, with instrument ID AF_DEFAULT_INST

     - instrument configuration parameters
          default instrument configuration for AIFF-C (and AIFF) is:
          AF_INST_MIDI_BASENOTE         60  MIDI
          AF_INST_NUMCENTS_DETUNE       0   cents
          AF_INST_MIDI_LONOTE           0   MIDI
          AF_INST_MIDI_HINOTE           127 MIDI
          AF_INST_MIDI_LOVELOCITY       1   MIDI
          AF_INST_MIDI_HIVELOCITY       127 MIDI
          AF_INST_NUMDBS_GAIN           0   dB
          AF_INST_SUSLOOPID             1    loop ID for sustain loop
          AF_INST_RELLOOPID             2    loop ID for release loop

     - loops
          two loops with ID's {1,2}
          default mode for each loop is AF_LOOP_MODE_NOLOOP (ignore loop)

     For file formats other than AIFF and AIFF-C, a default audio format and
     file configuration (i.e., number of tracks, insts, loops, etc.) is
     generated when afOpenFile(3dm) or its equivalent is called.  This means
     that an application does not need to initialize any parameters in the
     setup structure prior to calling afOpenFile(3dm) other than the sample
     format itself (see afInitFileFormat(3dm)), unless a custom configuration
     is desired.  The afQuery(3dm) routine provides a mechanism for retrieving
     informnation about default sample formats and widths for each file
     format, plus information about supported track, inst, loop, marker, and
     misc chunks.


READING RAW AUDIO FILES
     When opening raw audio files with read access, i.e., files with no header
     or with unrecognizable header formats, afOpenFile(3dm) and its related
     routines must be passed a AFfilesetup struct initialized to the exact
     format parameters of the raw file.  Most especially, the file format
     parameter must be set to AF_FILE_RAWDATA for all raw reads, regardless of
     the "actual" header type.

     The default values produced by afNewFileSetup() are for use when creating
     new files with write-access only.

SEE ALSO
     afInitFileFormat(3dm), afInitChannels(3dm), afInitLoopIDs(3dm),
     afInitMarkIDs(3dm), afInitMiscIDs(3dm), afInitRate(3dm),
     afInitSampleFormat(3dm)
     afOpenFile(3dm), afFreeFileSetup(3dm)


                                                                        Page 3