afWriteFrames(3dm)                                          afWriteFrames(3dm)


NAME
     afWriteFrames - write audio sample frames to a specified track in an
     audio file

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afWriteFrames(const AFfilehandle file, int track,
                       void *samples, const int count)

PARAMETER
     file      expects the AFfilehandle structure for the audio file to which
               audio sample data will be written.  This structure is usually
               the returned value of a call to afOpenFile(3dm).

     track     is an integer which identifies the audio track (chunk) in the
               file to be accessed.  Since all currently supported file
               formats allow at most one audio track per file, the value
               AF_DEFAULT_TRACK should always be used for this argument for
               now.

     samples   is a pointer to a buffer containing samples to be written to
               the audio file.

     count     expects the number of sample frames you want to write to the
               audio track.  For a stereo track, a sample frame would consist
               of a <left, right> sample pair.  For a monaural track, a sample
               frame would be a single sample.

RETURN VALUE
     afWriteFrames() returns the number of sample frames written to the
     internal track.  The return value normally is greater than or equal to 0.
     In the event of an error, afWriteFrames() will return -1, and the error
     value can be retrieved via oserror(3C).

DESCRIPTION
     afWriteFrames() writes data to the specified track of an audio file from
     the samples buffer.

     afWriteFrames() attempts to write count sample frames from the samples
     buffer to the track, starting at the current location of the file write
     pointer within the track. samples should be of type signed char*,
     unsigned char*, short*, int*, unsigned int*, float*, or double* depending
     on the width and format of the samples in the audio track as set using
     afInitSampleFormat(3dm).

     When an audio file is opened with write access by afOpenFile(3dm) or
     afOpenFD(3dm), the logical write pointer for the audio data is
     initialized to point to the location of the first sample frame in the
     track.


     Before returning, afWriteFrames() automatically updates the logical write
     pointer for track so that it points to the location of the sample frame
     following the last one written to the file.

     The samples buffer is interpreted differently depending on the current
     configuration of the audio track.  In particular, the sampwidth parameter
     may or may not be meaningful, depending on what the sampfmt parameter is.
     See afGetSampleFormat(3dm) for a full explanation of sample
     representations.

     afWriteFrames() automatically compresses data for audio tracks which are
     encoded using the CCITT G.722, CCITT G.711, MPEG, and Aware
     MultiRate/Lossless algorithms.  The data is passed to afWriteFrames()
     from an application program in the standard two's complement linear PCM
     format, but this is by no means guaranteed for later compression types
     (see afGetCompression(3dm) for more information about this).  You select
     a compression scheme for an audio track by calling
     afInitCompression(3dm).  To achieve real-time G.722 compression, the
     application process may require non-degrading scheduling priority (see
     schedctl(2) or npri(1))

     If an audio track contains data for more than a single audio channel, the
     data placed in the samples buffer should be interleaved. Sample data to
     be written to a stereo file should be buffered as a sequence of
     left/right pairs (sample "frames").  Interleave conventions for files
     containing  multichannel audio data are described in the AIFF-C
     specification.

EXAMPLE
     Example: to write 10000 stereo 16-bit sample pairs to a stereo AIFF-C
     file, place 20000 individual samples (i.e., 10000 <left, right> sample
     pairs) into a short[] buffer, and pass the buffer to afWriteFrames() with
     count set to 10000.

CAVEATS
     This routine will not function correctly if the user changes the file
     position on the file descriptor for the AFfilehandle being manipulated.
     See the section CAVEATS FOR USING THE HANDLE'S FILE DESCRIPTOR in
     afIntro(3dm) for some important information about how to deal with this
     situation.

SEE ALSO
     afOpenFile(3dm), afSeekFrame(3dm), afInitSampleFormat(3dm)


                                                                        Page 2