1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  */
5 
6 #ifndef CRAS_DSP_PIPELINE_H_
7 #define CRAS_DSP_PIPELINE_H_
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 #include <stdint.h>
14 
15 #include "cras_dsp_ini.h"
16 
17 /* These are the functions to create and use dsp pipelines. A dsp
18  * pipeline is a collection of dsp plugins that process audio
19  * data. The plugins and their connections are specified in an ini
20  * file. Before using the pipeline, we need to instantiate the
21  * pipeline by giving an audio sampling rate. Then we get the pointers
22  * to the input buffers, fill the input data, run the pipeline, and
23  * obtain the processed data from the output buffers.
24  */
25 
26 /* The maximum number of samples that cras_dsp_pipeline_run() can
27  * accept. Beyond this the user should break the samples into several
28  * blocks and call cras_dsp_pipeline_run() several times.
29  */
30 #define DSP_BUFFER_SIZE 2048
31 
32 struct pipeline;
33 
34 /* Creates a pipeline from the given ini file.
35  * Args:
36  *    ini - The ini file the pipeline is created from.
37  *    env - The expression environment for evaluating disable expression.
38  *    purpose - The purpose of the pipeline, "playback" or "capture".
39  * Returns:
40  *    A pointer to the pipeline, or NULL if the creation fails.
41  */
42 struct pipeline *cras_dsp_pipeline_create(struct ini* ini,
43 					  struct cras_expr_env *env,
44 					  const char *purpose);
45 
46 /* Frees the resources used by the pipeline. */
47 void cras_dsp_pipeline_free(struct pipeline *pipeline);
48 
49 /* Loads the implementation of the plugins in the pipeline (from
50  * shared libraries). Must be called before
51  * cras_dsp_pipeline_instantiate().
52  * Returns:
53  *    0 if successful. -1 otherwise.
54  */
55 int cras_dsp_pipeline_load(struct pipeline *pipeline);
56 
57 /* Instantiates the pipeline given the sampling rate.
58  * Args:
59  *    sample_rate - The audio sampling rate.
60  * Returns:
61  *    0 if successful. -1 otherwise.
62  */
63 int cras_dsp_pipeline_instantiate(struct pipeline *pipeline, int sample_rate);
64 
65 /* The counterpart of cras_dsp_pipeline_instantiate(). To change the
66  * sampling rate, this must be called before another call to
67  * cras_dsp_pipeline_instantiate(). */
68 void cras_dsp_pipeline_deinstantiate(struct pipeline *pipeline);
69 
70 /* Returns the buffering delay of the pipeline. This should only be called
71  * after a pipeline has been instantiated.
72  * Returns:
73  *    The buffering delay in frames.
74  */
75 int cras_dsp_pipeline_get_delay(struct pipeline *pipeline);
76 
77 /* Returns the number of input/output audio channels this pipeline expects */
78 int cras_dsp_pipeline_get_num_input_channels(struct pipeline *pipeline);
79 int cras_dsp_pipeline_get_num_output_channels(struct pipeline *pipeline);
80 
81 /* Returns the pointer to the input buffer for a channel of this
82  * pipeline. The size of the buffer is DSP_BUFFER_SIZE samples, and
83  * the number of samples acually used should be passed to
84  * cras_dsp_pipeline_run().
85  *
86  * Args:
87  *    index - The channel index. The valid value is 0 to
88  *            cras_dsp_pipeline_get_num_channels() - 1.
89  */
90 float *cras_dsp_pipeline_get_source_buffer(struct pipeline *pipeline,
91 					   int index);
92 
93 /* Returns the pointer to the output buffer for a channel of this
94  * pipeline. The size of the buffer is DSP_BUFFER_SIZE samples.
95  *
96  * Args:
97  *    index - The channel index. The valid value is 0 to
98  *            cras_dsp_pipeline_get_num_channels() - 1.
99  */
100 float *cras_dsp_pipeline_get_sink_buffer(struct pipeline *pipeline, int index);
101 
102 /* Returns the number of internal audio buffers allocated by the
103  * pipeline. This is used by the unit test only */
104 int cras_dsp_pipeline_get_peak_audio_buffers(struct pipeline *pipeline);
105 
106 /* Returns the sampling rate passed by cras_dsp_pipeline_instantiate(),
107  * or 0 if is has not been called */
108 int cras_dsp_pipeline_get_sample_rate(struct pipeline *pipeline);
109 
110 /* Processes a block of audio samples. sample_count should be no more
111  * than DSP_BUFFER_SIZE */
112 void cras_dsp_pipeline_run(struct pipeline *pipeline, int sample_count);
113 
114 /* Add a statistic of running time for the pipeline.
115  *
116  * Args:
117  *    time_delta - The time it takes to run the pipeline and any other
118  *                 preprocessing and postprocessing.
119  *    samples - The number of audio sample frames processed.
120  */
121 void cras_dsp_pipeline_add_statistic(struct pipeline *pipeline,
122 				     const struct timespec *time_delta,
123 				     int samples);
124 
125 /* Runs the specified pipeline across the given interleaved buffer in place.
126  * Args:
127  *    pipeline - The pipeline to run.
128  *    buf - The samples to be processed, interleaved.
129  *    frames - the numver of samples in the buffer.
130  */
131 void cras_dsp_pipeline_apply(struct pipeline *pipeline,
132 			     uint8_t *buf, unsigned int frames);
133 
134 #ifdef __cplusplus
135 } /* extern "C" */
136 #endif
137 
138 #endif /* CRAS_DSP_PIPELINE_H_ */
139