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 (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 /* 22 * Copyright (C) 4Front Technologies 1996-2008. 23 * 24 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 25 * Use is subject to license terms. 26 */ 27 28 /* 29 * Purpose: GRC library version 3.1 internal definitions 30 * 31 * GRC3 is a high quality sample rate conversion module that uses fixed point 32 * arithmetic. 33 */ 34 35 #ifndef AUDIO_GRC3_H 36 #define AUDIO_GRC3_H 37 38 #define GRC3_MAXHISTORY 4096 39 40 #ifdef __cplusplus 41 extern "C" 42 { 43 #endif 44 45 typedef struct grc3state { 46 uint32_t srcrate; 47 uint32_t dstrate; 48 uint32_t ptr; 49 uint32_t ptr_incv; 50 51 uint32_t sat; 52 uint32_t filtfactor; 53 int32_t *historyptr; 54 int32_t dummy_pad1; 55 56 int32_t history[GRC3_MAXHISTORY * 2]; 57 58 uint32_t outsz; 59 } grc3state_t; 60 61 62 /* BEGIN CSTYLED */ 63 /***************************************************************************** 64 65 Tutorial on how to use GRC3 rate conversion 66 67 1. First, you create an instance of grc3state_t for each channel. If you 68 are working with stereo files - you will need 2 of such instances, 69 for quadro - 4. 70 71 The instances may be allocated in either static or dynamic memory - that 72 makes no difference to the convertor. So, if your program has to process 73 one stereo stream, there's no reason why should you use malloc/free to 74 allocate/deallocate structures. Also, in device drivers, you can 75 use static variables as well: 76 77 static grc3state_t grc[2]; // for two channels 78 79 80 2. Before starting any conversion, grc3state_t instances should be initialized 81 properly, and you do this with grc3_setup function. Function itself does 82 not allocate additional memory or change anything except grc3state_t 83 structure, so this is thread safe, and you don't have to do additional 84 "deinitialization". 85 86 If you are doing interleaved audio (stereo/quadro/whatever) conversion, 87 you should do setup on each of the channels, and should have separate 88 instance of grc3state_t for each channel. As you will understand further, 89 such conversion is done separately. And now, the setup function: 90 91 int grc3_setup( grc3state_t *grc, 92 uint32_t fromRate, 93 uint32_t toRate ); 94 95 grc - pointer to grc3state_t instance 96 fromRate - source sample rate 97 toRate - destination sample rate 98 99 Note, that sample rates itself are not important - the important thing 100 is ratio between those sample rates. So, for example, if you have to 101 convert from 24000Hz to 48000Hz, it's ok to write: 102 103 grc3_setup( &grc[0], 240, 480 ); 104 105 Sometimes (in MIDI synths) it would be desired to use fractional sample 106 rates. For example, setup for conversion from 33100.78 to 48000 may look 107 like this: 108 109 grc3_setup( &grc[0], 3310078, 4800000); 110 111 Note, that on stereo, GRC3 setup will look like this: 112 113 static grc3state_t grc[2]; 114 115 // ... 116 117 grc3_setup( &grc[0], 3310078, 4800000) 118 grc3_setup( &grc[1], 3310078, 4800000); 119 120 121 Note, that you should not rely on grc3_setup's fast execution or any 122 execution timing. It may contain some massive arithmetic and even huge 123 loops, so avoid putting grc3_setup to inner loops and calling in 124 latency-dependent code. 125 126 127 3. Next, before running a stream through grc3_convert function, you should 128 reset each of grc3state_t instance used: 129 130 void grc3_reset(grc3state_t *grc); 131 132 133 grc - pointer to GRC3 instance variable 134 135 So, for stereo, this appears to be: 136 137 static grc3state_t grc[2]; 138 139 // ... 140 141 grc3_reset( &grc[0] ); 142 grc3_reset( &grc[1] ); 143 144 145 4. Finally, doing conversion is easy: 146 147 void grc3_convert( grc3state_t *grc, 148 int domain, 149 int quality, 150 const void *src, 151 void *dst, 152 int maxInSize, 153 int maxOutSize, 154 int interleave, 155 int offset ); 156 157 158 grc - pointer to initialized grc3state_t instance; you 159 can specify NULL to check whether a particular 160 domain/quality pair is supported, check return value 161 162 quality - quality to use for conversion, supported values are: 163 164 0 - D lowest quality (normally equals to low quality) 165 1 - L low quality (spline interpolation) 166 2 - M medium quality (lagrange interpolation) 167 3 - H high quality 168 4 - HX high quality (high quality with extra precision) 169 5 - P production quality 170 171 6 - PX production quality (prod quality with extra precision) 172 (PX is currently disabled because it causes a crash) 173 174 src - source audio buffer 175 176 dst - destination audio buffer; 177 178 maxInSize - size of input buffer (in samples per channel!) 179 180 maxOutSize - size of output buffer (in samples per channel!) 181 (will never overrun this size) 182 183 interleave - interleave factor; for MONO or non-interleaved data 184 it should be equal to 1; 185 186 2 - STEREO interleaved audio 187 4 - QUADRO interleaved audio 188 189 So, basically, this parameter should be equal to number 190 of interleaved channels 191 192 offset - number of interleaved channel currently processing, 193 starting from 0; for MONO or non-interleaved data 194 it should be equal to 0 195 196 197 For unsupported quality values, it will fall back to 198 "D" quality (the lowest one) 199 200 also on return it sets: 201 202 grc->outsz == number of output samples 203 204 Note, that if quality is not supported, 205 calling the function with real data will fall back 206 to the worst quality available. 207 208 Note that this version of GRC3 only supports 24-bit 209 native endian. (Modified by Sun for performance.) 210 211 212 213 5. Interleaved processing of N channels is done like this: 214 215 216 static grc3state_t grc[N]; 217 int t; 218 219 //... 220 221 222 for(t=0; t<N; t++) 223 { 224 grc3_setup( &grc[t], 22050, 48000 ); 225 226 grc3_reset( &grc[t] ); 227 } 228 229 230 //... 231 232 while (...) { 233 234 for(t = 0; t < N; t++) { 235 grc3_convert(&grc[t], // instance pointer 236 4, // quality 237 in_buffer, // input buffer 238 out_buffer, // input buffer 239 in_samples_count, // number of samples 240 // in in_buffer 241 2048, // size of out_buffer 242 N, t // num of channels, channel# 243 ); 244 } 245 246 247 // Normally, for interleaved data, ->outsz of all instances will 248 // be the same for the same stream 249 250 put_sound_somewhere(out_buffer, 251 grc[0]->outsz * N * sizeof(out_buffer[0]) ); 252 } 253 254 255 6. If you use the same storage and the same setup for processing few separate 256 non-related sounds, to prevent the feedback of sound1's tail to sound2's 257 beginning - do grc3_reset on the state instances before calling 258 grc_convert. 259 260 ***************************************************************************** 261 */ 262 /* END CSTYLED */ 263 264 void grc3_setup(grc3state_t *, uint32_t fromRate, uint32_t toRate); 265 266 void grc3_reset(grc3state_t *); 267 268 void grc3_convert(grc3state_t *, int quality, 269 const void *src, void *dst, int sz, int bufsz, int inc, int offset); 270 271 #ifdef __cplusplus 272 }; 273 #endif 274 275 #endif /* AUDIO_GRC3_H */ 276