usr/src/cmd/audio/include/AudioHdr.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright (c) 1992-2001 by Sun Microsystems, Inc.
  24  * All rights reserved.
  25  */
  26
  27 #ifndef _MULTIMEDIA_AUDIOHDR_H
  28 #define _MULTIMEDIA_AUDIOHDR_H
  29
  30 #pragma ident   "%Z%%M% %I%     %E% SMI"
  31
  32 #ifdef NO_EXTERN_C
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #endif /* NO_EXTERN_C */
  39
  40 #include <AudioTypes.h>
  41 #include <AudioError.h>
  42 #include <audio_hdr.h>
  43
  44 // Required for the use of MAXSHORT
  45 #include <values.h>
  46
  47 // Required by htons() and other network services.
  48 #include <sys/types.h>
  49 #include <netinet/in.h>
  50
  51 // Define an in-core audio data header.
  52 //
  53 // This is different than the on-disk file header.
  54 //
  55 //
  56 // The audio header contains the following fields:
  57 //
  58 //      sample_rate             Number of samples per second (per channel).
  59 //
  60 //      samples_per_unit        This field describes the number of samples
  61 //                                represented by each sample unit (which, by
  62 //                                definition, are aligned on byte boundaries).
  63 //                                Audio samples may be stored individually
  64 //                                or, in the case of compressed formats
  65 //                                (e.g., ADPCM), grouped in algorithm-
  66 //                                specific ways.  If the data is bit-packed,
  67 //                                this field tells the number of samples
  68 //                                needed to get to a byte boundary.
  69 //
  70 //      bytes_per_unit          Number of bytes stored for each sample unit
  71 //
  72 //      channels                Number of interleaved sample units.
  73 //                                 For any given time quantum, the set
  74 //                                 consisting of 'channels' sample units
  75 //                                 is called a sample frame.  Seeks in
  76 //                                 the data should be aligned to the start
  77 //                                 of the nearest sample frame.
  78 //
  79 //      encoding                Data encoding format.
  80 //
  81 //
  82 // The first four values are used to compute the byte offset given a
  83 // particular time, and vice versa.  Specifically:
  84 //
  85 //      seconds = offset / C
  86 //      offset = seconds * C
  87 // where:
  88 //      C = (channels * bytes_per_unit * sample_rate) / samples_per_unit
  89
  90
  91 // Define the possible encoding types.
  92 // XXX - As long as audio_hdr.h exists, these values should match the
  93 //       corresponding fields in audio_hdr.h since the cast operator
  94 //       copies them blindly.  This implies that the values should
  95 //       match any of the encodings that appear in <sys/audioio.h> also.
  96 // XXX - How can encoding types be added dynamically?
  97 enum AudioEncoding {
  98         NONE = 0,       // no encoding type set
  99         ULAW = 1,       // ISDN u-law
 100         ALAW = 2,       // ISDN A-law
 101         LINEAR = 3,     // PCM 2's-complement (0-center)
 102         FLOAT = 100,    // IEEE float (-1. <-> +1.)
 103         G721 = 101,     // CCITT G.721 ADPCM
 104         G722 = 102,     // CCITT G.722 ADPCM
 105         G723 = 103,     // CCITT G.723 ADPCM
 106         DVI = 104       // DVI ADPCM
 107 };
 108
 109 // The byte order of the data.  This is only applicable if the data
 110 // is 16-bit.  All variables of this type will have the prefix "endian".
 111 enum AudioEndian {
 112         BIG_ENDIAN = 0, // Sun and network byte order
 113         LITTLE_ENDIAN = 1,  // Intel byte order
 114         SWITCH_ENDIAN = 2,  // Flag to switch to the opposite endian, used
 115                             // by coerceEndian().
 116         UNDEFINED_ENDIAN = -1
 117 };
 118
 119 // Define a public data header structure.
 120 // Clients must be able to modify multiple fields inbetween validity checking.
 121 class AudioHdr {
 122 public:
 123         unsigned int    sample_rate;            // samples per second
 124         unsigned int    samples_per_unit;       // samples per unit
 125         unsigned int    bytes_per_unit;         // bytes per sample unit
 126         unsigned int    channels;               // # of interleaved channels
 127         AudioEncoding   encoding;               // data encoding format
 128         AudioEndian     endian;                 // byte order
 129
 130         AudioHdr():                                     // Constructor
 131             sample_rate(0), samples_per_unit(0), bytes_per_unit(0),
 132             channels(0), encoding(NONE)
 133             {
 134                 // The default for files is BIG, but this is
 135                 // set in the AudioUnixfile class.
 136                 endian = localByteOrder();
 137             }
 138
 139         AudioHdr(Audio_hdr hdr):                // Constructor from C struct
 140             sample_rate(hdr.sample_rate),
 141             samples_per_unit(hdr.samples_per_unit),
 142             bytes_per_unit(hdr.bytes_per_unit),
 143             channels(hdr.channels),
 144             encoding((AudioEncoding)hdr.encoding)
 145             {
 146                 // The default for files is BIG, but this is
 147                 // set in the AudioUnixfile class.
 148                 endian = localByteOrder();
 149             }
 150
 151         // Determines the local byte order, otherwise know as the endian
 152         // nature of the current machine.
 153         AudioEndian localByteOrder() const;
 154
 155         virtual void Clear();                           // Init header
 156         virtual AudioError Validate() const;            // Check hdr validity
 157
 158         // Conversion between time (in seconds) and byte offsets
 159         virtual Double Bytes_to_Time(off_t cnt) const;
 160         virtual off_t Time_to_Bytes(Double sec) const;
 161
 162         // Round down a byte count to a sample frame boundary
 163         virtual off_t Bytes_to_Bytes(off_t& cnt) const;
 164         virtual size_t Bytes_to_Bytes(size_t& cnt) const;
 165
 166         // Conversion between time (in seconds) and sample frames
 167         virtual Double Samples_to_Time(unsigned long cnt) const;
 168         virtual unsigned long Time_to_Samples(Double sec) const;
 169
 170         // Return the number of bytes in a sample frame for the audio encoding.
 171         virtual unsigned int FrameLength() const;
 172
 173         // Return some meaningful strings.  The returned char pointers
 174         // must be deleted when the caller is through with them.
 175         virtual char *RateString() const;       // eg "44.1kHz"
 176         virtual char *ChannelString() const;    // eg "stereo"
 177         virtual char *EncodingString() const;   // eg "3-bit G.723"
 178         virtual char *FormatString() const;     // eg "4-bit G.721, 8 kHz, mono"
 179
 180         // Parse strings and set corresponding header fields.
 181         virtual AudioError RateParse(char *);
 182         virtual AudioError ChannelParse(char *);
 183         virtual AudioError EncodingParse(char *);
 184         virtual AudioError FormatParse(char *);
 185
 186         // for casting to C Audio_hdr struct
 187         operator Audio_hdr() {
 188                 Audio_hdr hdr;
 189
 190                 hdr.sample_rate = sample_rate;
 191                 hdr.samples_per_unit = samples_per_unit;
 192                 hdr.bytes_per_unit = bytes_per_unit;
 193                 hdr.channels = channels;
 194                 hdr.encoding = encoding;
 195                 hdr.endian = endian;
 196                 return (hdr);
 197         };
 198
 199         // compare two AudioHdr objects
 200         int operator == (const AudioHdr& tst)
 201         {
 202                 return ((sample_rate == tst.sample_rate) &&
 203                     (samples_per_unit == tst.samples_per_unit) &&
 204                     (bytes_per_unit == tst.bytes_per_unit) &&
 205                     (channels == tst.channels) &&
 206 // Audioconvert uses this method to see if a conversion should take
 207 // place, but doesn't know how to convert between endian formats.
 208 // This makes it ignore endian differences.
 209 //                  (endian = tst.endian) &&
 210                     (encoding == tst.encoding));
 211         }
 212         int operator != (const AudioHdr& tst)
 213         {
 214                 return (! (*this == tst));
 215         }
 216 };
 217
 218 #ifdef NO_EXTERN_C
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* NO_EXTERN_C */
 225
 226 #endif /* !_MULTIMEDIA_AUDIOHDR_H */