← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/oss4/oneiric-proposed

« back to all changes in this revision

Viewing changes to kernel/framework/include/grc3.h

  • Committer: Bazaar Package Importer
  • Author(s): Stefano Rivera
  • Date: 2011-06-16 20:37:48 UTC
  • mfrom: (5.1.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110616203748-jbrxik6ql33z54co
Tags: 4.2-build2004-1ubuntu1
https://launchpad.net/bugs/746048
https://launchpad.net/bugs/770972
* Merge from Debian unstable.
  - Supports our current kernel (LP: #746048)
  Remaining changes:
  - debian/oss4-dkms.dkms.in: s/source/build/ in Kernel headers paths.
* ld-as-needed.patch: Re-order CC arguments to enable building with ld
  --as-needed (LP: #770972)

Show diffs side-by-side

added added

removed removed

Lines of Context:
kernel/framework/include/grc3.h
 
1
/*
 
2
 * Purpose: GRC library version 3.1 internal definitions
 
3
 *
 
4
 * GRC3 is a high quality sample rate conversion module that uses fixed point
 
5
 * arithmetic.
 
6
 */
 
7
/*
 
8
 *
 
9
 * This file is part of Open Sound System.
 
10
 *
 
11
 * Copyright (C) 4Front Technologies 1996-2008.
 
12
 *
 
13
 * This this source file is released under GPL v2 license (no other versions).
 
14
 * See the COPYING file included in the main directory of this source
 
15
 * distribution for the license terms and conditions.
 
16
 *
 
17
 */
 
18
 
 
19
#ifndef GRC3_H_INCLUDED
 
20
#define GRC3_H_INCLUDED
 
21
 
 
22
#if !defined(CONFIG_OSS_GRC_MIN_QUALITY) || CONFIG_OSS_GRC_MIN_QUALITY > 6
 
23
#define CONFIG_OSS_GRC_MIN_QUALITY 0
 
24
#endif
 
25
 
 
26
#if !defined(CONFIG_OSS_GRC_MAX_QUALITY) || CONFIG_OSS_GRC_MAX_QUALITY < CONFIG_OSS_GRC_MIN_QUALITY
 
27
#define CONFIG_OSS_GRC_MAX_QUALITY 6
 
28
#endif
 
29
 
 
30
 
 
31
#if (CONFIG_OSS_GRC_MIN_QUALITY<=1)&&(CONFIG_OSS_GRC_MAX_QUALITY>=0)
 
32
#define GRC3_COMPILE_L
 
33
#endif
 
34
 
 
35
#if (CONFIG_OSS_GRC_MIN_QUALITY<=2)&&(CONFIG_OSS_GRC_MAX_QUALITY>=2)
 
36
#define GRC3_COMPILE_M
 
37
#endif
 
38
 
 
39
#if (CONFIG_OSS_GRC_MIN_QUALITY<=4)&&(CONFIG_OSS_GRC_MAX_QUALITY>=3)
 
40
#define GRC3_COMPILE_H
 
41
#endif
 
42
 
 
43
#if (CONFIG_OSS_GRC_MIN_QUALITY<=6)&&(CONFIG_OSS_GRC_MAX_QUALITY>=5)
 
44
#define GRC3_COMPILE_P
 
45
#endif
 
46
 
 
47
#if (CONFIG_OSS_GRC_MIN_QUALITY<=3)
 
48
    #if (CONFIG_OSS_GRC_MAX_QUALITY>=3)
 
49
        #define DEFAULT_GRC_QUALITY 3
 
50
    #else
 
51
        #define DEFAULT_GRC_QUALITY CONFIG_OSS_GRC_MAX_QUALITY
 
52
    #endif
 
53
#else
 
54
    #define DEFAULT_GRC_QUALITY CONFIG_OSS_GRC_MIN_QUALITY
 
55
#endif
 
56
 
 
57
 
 
58
#define GRCinline inline static
 
59
#define GRCpreg   register
 
60
#define GRCvreg   register
 
61
 
 
62
 
 
63
#define GRC3_MAXHISTORY 4096
 
64
 
 
65
#ifdef __cplusplus
 
66
extern "C"
 
67
{
 
68
#endif
 
69
 
 
70
  typedef struct s_grc3state_t
 
71
  {
 
72
    uint32_t srcrate;
 
73
    uint32_t dstrate;
 
74
    uint32_t ptr;
 
75
    uint32_t ptr_incv;
 
76
 
 
77
    uint32_t sat;
 
78
    uint32_t filtfactor;
 
79
    int32_t *historyptr;
 
80
    int32_t dummy_pad1;
 
81
 
 
82
    int32_t history[GRC3_MAXHISTORY * 2];
 
83
 
 
84
    uint32_t insz;
 
85
    uint32_t outsz;
 
86
  }
 
87
  grc3state_t;
 
88
 
 
89
 
 
90
/*****************************************************************************
 
91
 
 
92
    Tutorial on how to use GRC3 rate conversion
 
93
    
 
94
1.  First, you create an instance of grc3state_t for each channel. If you 
 
95
    are working with stereo files - you will need 2 of such instances,
 
96
    for quadro - 4.
 
97
    
 
98
    The instances may be allocated in either static or dynamic memory - that
 
99
    makes no difference to the convertor. So, if your program has to process
 
100
    one stereo stream, there's no reason why should you use malloc/free to 
 
101
    allocate/deallocate structures. Also, in device drivers, you can 
 
102
    use static variables as well:
 
103
    
 
104
        static grc3state_t grc[2]; // for two channels
 
105
 
 
106
    
 
107
2.  Before starting any conversion, grc3state_t instances should be initialized
 
108
    properly, and you do this with grc3_setup function. Function itself does
 
109
    not allocate additional memory or change anything except grc3state_t
 
110
    structure, so this is thread safe, and you don't have to do additional
 
111
    "deinitialization".
 
112
    
 
113
    If you are doing interleaved audio (stereo/quadro/whatever) conversion, 
 
114
    you should do setup on each of the channels, and should have separate
 
115
    instance of grc3state_t for each channel. As you will understand further,
 
116
    such conversion is done separately. And now, the setup function:
 
117
    
 
118
        int grc3_setup( grc3state_t *grc, 
 
119
                    uint32_t    fromRate,
 
120
                uint32_t    toRate );
 
121
               
 
122
        grc       - pointer to grc3state_t instance
 
123
        fromRate  - source sample rate
 
124
        toRate    - destination sample rate
 
125
        
 
126
        RETURNS   - 1 on success, and 0 if conversion is not supported
 
127
        
 
128
    Note, that sample rates itself are not important - the important thing 
 
129
    is ratio between those sample rates. So, for example, if you have to
 
130
    convert from 24000Hz to 48000Hz, it's ok to write:
 
131
    
 
132
        result = grc3_setup( &grc[0], 240, 480 );
 
133
    
 
134
    Sometimes (in MIDI synths) it would be desired to use fractional sample
 
135
    rates. For example, setup for conversion from 33100.78 to 48000 may look 
 
136
    like this:
 
137
    
 
138
        result = grc3_setup( &grc[0], 3310078, 4800000);
 
139
    
 
140
    Note, that on stereo, GRC3 setup will look like this:
 
141
    
 
142
        static grc3state_t grc[2];
 
143
    
 
144
    // ...
 
145
    
 
146
        result = 
 
147
        grc3_setup( &grc[0], 3310078, 4800000)
 
148
     && grc3_setup( &grc[1], 3310078, 4800000);    
 
149
    
 
150
 
 
151
    Note, that you should not rely on grc3_setup's fast execution or any
 
152
    execution timing. It may contain some massive arithmetic and even huge 
 
153
    loops, so avoid putting grc3_setup to inner loops and calling in 
 
154
    latency-dependent code.
 
155
 
 
156
        
 
157
3.  Next, before running a stream through grc3_convert function, you should
 
158
    reset each of grc3state_t instance used:
 
159
    
 
160
        int grc3_reset(grc3state_t *grc);
 
161
    
 
162
    
 
163
        grc     - pointer to GRC3 instance variable
 
164
 
 
165
            RETURNS - 1 on success, 0 on failure
 
166
    
 
167
    So, for stereo, this appears to be:
 
168
    
 
169
        static grc3state_t grc[2]; 
 
170
    
 
171
    // ...
 
172
    
 
173
        grc3_reset( &grc[0] );  
 
174
    grc3_reset( &grc[1] );
 
175
        
 
176
 
 
177
4.  Finally, doing conversion is easy:
 
178
 
 
179
        int grc3_convert( grc3state_t *grc,
 
180
                          int          domain, 
 
181
              int          quality, 
 
182
                          const void  *src, 
 
183
              void        *dst, 
 
184
                  int          maxInSize, 
 
185
              int          maxOutSize, 
 
186
              int          interleave,
 
187
              int          offset );
 
188
              
 
189
              
 
190
        grc        - pointer to initialized grc3state_t instance; you
 
191
                     can specify NULL to check whether a particular
 
192
                 domain/quality pair is supported, check return value
 
193
        
 
194
        domain     - number of bits in stream;
 
195
                     supported values are 8, 16, 32, -16, -32;
 
196
                
 
197
                 minus sign stands for swapped-endian conversion; that
 
198
                 will do big-endian conversion on little-endian machines
 
199
                 and little-endian conversion on big-endian machines
 
200
               
 
201
        quality    - quality to use for conversion, supported values are:
 
202
        
 
203
                     0 - D lowest quality (normally equals to low quality)
 
204
                 1 - L  low quality    (spline interpolation)
 
205
                 2 - M  medium quality (lagrange interpolation)
 
206
                 3 - H  high quality   
 
207
                 4 - HX high quality   (high quality with extra precision)
 
208
                 5 - P  production quality
 
209
 
 
210
                 6 - PX production quality (prod quality with extra precision)
 
211
                     (PX is currently disabled because it causes a crash)
 
212
               
 
213
        src        - source audio buffer          
 
214
        
 
215
        dst        - destination audio buffer; 
 
216
        
 
217
        maxInSize  - size of input buffer (in samples per channel!)
 
218
        
 
219
        maxOutSize - size of output buffer (in samples per channel!)
 
220
                     (will never overrun this size)
 
221
        
 
222
        interleave - interleave factor; for MONO or non-interleaved data
 
223
                     it should be equal to 1;
 
224
             
 
225
             2 - STEREO interleaved audio
 
226
             4 - QUADRO interleaved audio
 
227
             
 
228
             So, basically, this parameter should be equal to number
 
229
             of interleaved channels
 
230
             
 
231
        offset     - number of interleaved channel currently processing, 
 
232
                     starting from 0; for MONO or non-interleaved data
 
233
             it should be equal to 0
 
234
             
 
235
             
 
236
        RETURNS    in case of grc != NULL
 
237
        
 
238
                   - actual number if INPUT samples processed, 
 
239
                 or -1 in case if conversion is not supported;
 
240
             
 
241
             For unsupported quality values, it will fall back to
 
242
             "D" quality (the lowest one)
 
243
                     
 
244
                     also on return it sets:
 
245
             
 
246
             grc->insz   == number of input samples processed
 
247
             grc->outsz  == number of output samples
 
248
             
 
249
             
 
250
             
 
251
        RETURNS    in case of grc == NULL            
 
252
        
 
253
                  -  will return 0 in case quality/domain pair is supported
 
254
              
 
255
                 if specified quality and/or bitdepth is not supported,
 
256
             then function will return -1
 
257
             
 
258
             Note, that if quality is not supported but bitdepth is,
 
259
             calling the function with real data will fall back
 
260
             to the worst quality available.             
 
261
             
 
262
             
 
263
             
 
264
5.  Interleaved processing of N channels is done like this:
 
265
 
 
266
    
 
267
        static grc3state_t grc[N]; 
 
268
    int t;  
 
269
 
 
270
    //...
 
271
    
 
272
 
 
273
    for(t=0; t<N; t++)
 
274
    {
 
275
        grc3_setup( &grc[t], 22050, 48000 );
 
276
        
 
277
        grc3_reset( &grc[t] );
 
278
    }
 
279
 
 
280
    
 
281
    //...
 
282
    
 
283
        while (...)
 
284
    {
 
285
      
 
286
        for(t=0; t<N; t++)
 
287
        {
 
288
            grc3_convert( 
 
289
                      &grc[t], // instance pointer
 
290
                      
 
291
                      16, 4,   // numbits, quality
 
292
        
 
293
                      in_buffer,  // input buffer
 
294
                  out_buffer, // input buffer
 
295
                  
 
296
                  in_samples_count, // number of samples
 
297
                                    // in in_buffer
 
298
                  2048, // size of out_buffer
 
299
                  
 
300
                  N, t  // num of channels, channel#
 
301
                  
 
302
                );
 
303
        }
 
304
        
 
305
        
 
306
        // Normally, for interleaved data, ->outsz of all instances will
 
307
        // be the same for the same stream
 
308
        
 
309
        put_sound_somewhere( out_buffer, 
 
310
                             grc[0]->outsz * N * sizeof(out_buffer[0]) );                       
 
311
        
 
312
    }
 
313
    
 
314
    
 
315
6.  If you use the same storage and the same setup for processing few separate
 
316
    non-related sounds, to prevent the feedback of sound1's tail to sound2's 
 
317
    beginning - do grc3_reset on the state instances before calling 
 
318
    grc_convert.
 
319
    
 
320
******************************************************************************/
 
321
 
 
322
 
 
323
  int grc3_setup (grc3state_t * grc, uint32_t fromRate, uint32_t toRate);
 
324
 
 
325
  int grc3_reset (grc3state_t * grc);
 
326
 
 
327
  int grc3_convert (grc3state_t * grc,
 
328
                    int domain, int quality,
 
329
                    void *src, void *dst,
 
330
                    int sz, int bufsz, int inc, int offset);
 
331
 
 
332
 
 
333
  int32_t _clamp24 (int32_t v);
 
334
 
 
335
#ifdef __cplusplus
 
336
};
 
337
#endif
 
338
 
 
339
#endif