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 
AudioHdr()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 
AudioHdr(Audio_hdr hdr)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
Audio_hdr()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 */
227