GlueGen: src/java/com/jogamp/common/av/AudioFormat.java Source File

GlueGen v2.6.0-rc-20250712 GlueGen, Native Binding Generator for Java™ (public API).

AudioFormat.java
Go to the documentation of this file.
1/**
2 * Copyright 2013-2023 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28 package com.jogamp.common.av;
29
30/**
31 * Specifies the linear audio PCM format.
32 */
33 public class AudioFormat {
34 /**
35 * @param sampleRate sample rate in Hz (1/s), e.g. 44100 Hz
36 * @param sampleSize sample size in bits, e.g. 16 bits
37 * @param channelCount number of channels, e.g. 2 channels for stereo
38 * @param signed true if signed PCM values, false for unsigned values
39 * @param fixedP true for fixed point values, false for unsigned floating point values with a sampleSize of 32 (float) or 64 (double)
40 * @param planar true for planar data package (each channel in own data buffer), false for packed data channels interleaved in one buffer.
41 * @param littleEndian true for little-endian byte order, false for big endian byte order
42 */
43 public AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian) {
44 this.sampleRate = sampleRate;
45 this.sampleSize = sampleSize;
46 this.channelCount = channelCount;
47 this.signed = signed;
48 this.fixedP = fixedP;
49 this.planar = planar;
50 this.littleEndian = littleEndian;
51 if( !fixedP ) {
52 if( sampleSize != 32 && sampleSize != 64 ) {
53 throw new IllegalArgumentException("Floating point: sampleSize "+sampleSize+" bits");
54 }
55 if( !signed ) {
56 throw new IllegalArgumentException("Floating point: unsigned");
57 }
58 }
59 }
60
61 /** Sample rate in Hz (1/s, e.g. 44100 Hz. */
62 public final int sampleRate;
63 /** Sample size in bits, e.g. 16 bits. */
64 public final int sampleSize;
65 /** Number of channels, e.g. 2 channels for stereo. */
66 public final int channelCount;
67 /** Signed PCM values if true, otherwise unsigned values. */
68 public final boolean signed;
69 /** Fixed or floating point values. Floating point 'float' has {@link #sampleSize} 32, 'double' has {@link #sampleSize} 64. */
70 public final boolean fixedP;
71 /** Planar or packed samples. If planar, each channel has their own data buffer. If packed, channel data is interleaved in one buffer. */
72 public final boolean planar;
73 /** Little-endian byte order if true, otherwise big endian byte order. */
74 public final boolean littleEndian;
75
76
77 //
78 // Time <-> Bytes
79 //
80
81 /**
82 * Returns the byte size of the given duration in seconds
83 * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
84 * <pre>
85 * final float bytesPerSample = sampleSize/8;
86 * return Math.round( duration * channelCount * bytesPerSample * sampleRate );
87 * </pre>
88 * <p>
89 * Time -> Byte Count
90 * </p>
91 * @param duration duration in seconds
92 */
93 public final int getDurationsByteSize(final float duration) {
94 final float bytesPerSample = sampleSize >>> 3; // /8
95 return Math.round( duration * channelCount * bytesPerSample * sampleRate );
96 }
97
98 /**
99 * Returns the duration in seconds of the given byte count
100 * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
101 * <pre>
102 * final float bytesPerSample = sampleSize/8;
103 * return byteCount / ( channelCount * bytesPerSample * sampleRate )
104 * </pre>
105 * <p>
106 * Byte Count -> Time
107 * </p>
108 * @param byteCount size in bytes
109 */
110 public final float getBytesDuration(final int byteCount) {
111 final float bytesPerSample = sampleSize >>> 3; // /8
112 return byteCount / ( channelCount * bytesPerSample * sampleRate );
113 }
114
115 /**
116 * Returns the duration in seconds of the given sample count per frame and channel
117 * according to the {@link #sampleRate}, i.e.
118 * <pre>
119 * (float)sampleCount / sampleRate
120 * </pre>
121 * <p>
122 * Sample Count -> Time
123 * </p>
124 * @param sampleCount sample count per frame and channel
125 */
126 public final float getSamplesDuration(final int sampleCount) {
127 return (float)sampleCount / sampleRate;
128 }
129
130 /**
131 * Returns the rounded frame count of the given duration and frame duration, both in seconds.
132 * <pre>
133 * Math.max(1, Math.round( duration / frameDuration ))
134 * </pre>
135 * <p>
136 * Note: <code>frameDuration</code> can be derived by <i>sample count per frame and channel</i>
137 * via {@link #getSamplesDuration(int)} or by <i>byte count</i> via {@link #getBytesDuration(int)}.
138 * </p>
139 * <p>
140 * Frame Time -> Frame Count
141 * </p>
142 * @param duration duration in seconds
143 * @param frameDuration duration per frame in seconds, i.e. 1/frame_rate
144 * @see #getSamplesDuration(int)
145 * @see #getBytesDuration(int)
146 */
147 public final int getFrameCount(final float duration, final float frameDuration) {
148 return Math.max(1, Math.round( duration / frameDuration ));
149 }
150
151 /**
152 * Returns the byte size of given sample count
153 * according to the {@link #sampleSize}, i.e.:
154 * <pre>
155 * sampleCount * ( sampleSize / 8 )
156 * </pre>
157 * <p>
158 * Note: To retrieve the byte size for all channels,
159 * you need to pre-multiply <code>sampleCount</code> with {@link #channelCount}.
160 * </p>
161 * <p>
162 * Sample Count -> Byte Count
163 * </p>
164 * @param sampleCount sample count
165 */
166 public final int getSamplesByteCount(final int sampleCount) {
167 return sampleCount * ( sampleSize >>> 3 );
168 }
169
170 /**
171 * Returns the sample count of given byte count
172 * according to the {@link #sampleSize}, i.e.:
173 * <pre>
174 * ( byteCount * 8 ) / sampleSize
175 * </pre>
176 * <p>
177 * Note: If <code>byteCount</code> covers all channels and you request the sample size per channel,
178 * you need to divide the result by <code>sampleCount</code> by {@link #channelCount}.
179 * </p>
180 * <p>
181 * Byte Count -> Sample Count
182 * </p>
183 * @param byteCount number of bytes
184 */
185 public final int getBytesSampleCount(final int byteCount) {
186 return ( byteCount << 3 ) / sampleSize;
187 }
188
189 @Override
190 public String toString() {
191 return "AudioFormat[sampleRate "+sampleRate+", sampleSize "+sampleSize+", channelCount "+channelCount+
192 ", signed "+signed+", fixedP "+fixedP+", "+(planar?"planar":"packed")+", "+(littleEndian?"little":"big")+"-endian]"; }
193}
com.jogamp.common.av.AudioFormat
Specifies the linear audio PCM format.
Definition: AudioFormat.java:33
com.jogamp.common.av.AudioFormat.fixedP
final boolean fixedP
Fixed or floating point values.
Definition: AudioFormat.java:70
com.jogamp.common.av.AudioFormat.getFrameCount
final int getFrameCount(final float duration, final float frameDuration)
Returns the rounded frame count of the given duration and frame duration, both in seconds.
Definition: AudioFormat.java:147
com.jogamp.common.av.AudioFormat.getSamplesByteCount
final int getSamplesByteCount(final int sampleCount)
Returns the byte size of given sample count according to the sampleSize, i.e.
Definition: AudioFormat.java:166
com.jogamp.common.av.AudioFormat.getBytesDuration
final float getBytesDuration(final int byteCount)
Returns the duration in seconds of the given byte count according to sampleSize, channelCount and sam...
Definition: AudioFormat.java:110
com.jogamp.common.av.AudioFormat.AudioFormat
AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian)
Definition: AudioFormat.java:43
com.jogamp.common.av.AudioFormat.getSamplesDuration
final float getSamplesDuration(final int sampleCount)
Returns the duration in seconds of the given sample count per frame and channel according to the samp...
Definition: AudioFormat.java:126
com.jogamp.common.av.AudioFormat.littleEndian
final boolean littleEndian
Little-endian byte order if true, otherwise big endian byte order.
Definition: AudioFormat.java:74
com.jogamp.common.av.AudioFormat.channelCount
final int channelCount
Number of channels, e.g.
Definition: AudioFormat.java:66
com.jogamp.common.av.AudioFormat.planar
final boolean planar
Planar or packed samples.
Definition: AudioFormat.java:72
com.jogamp.common.av.AudioFormat.sampleRate
final int sampleRate
Sample rate in Hz (1/s, e.g.
Definition: AudioFormat.java:62
com.jogamp.common.av.AudioFormat.toString
String toString()
Definition: AudioFormat.java:190
com.jogamp.common.av.AudioFormat.signed
final boolean signed
Signed PCM values if true, otherwise unsigned values.
Definition: AudioFormat.java:68
com.jogamp.common.av.AudioFormat.getDurationsByteSize
final int getDurationsByteSize(final float duration)
Returns the byte size of the given duration in seconds according to sampleSize, channelCount and samp...
Definition: AudioFormat.java:93
com.jogamp.common.av.AudioFormat.sampleSize
final int sampleSize
Sample size in bits, e.g.
Definition: AudioFormat.java:64
com.jogamp.common.av.AudioFormat.getBytesSampleCount
final int getBytesSampleCount(final int byteCount)
Returns the sample count of given byte count according to the sampleSize, i.e.
Definition: AudioFormat.java:185