|
| 1 | +/* |
| 2 | + * Copyright 2020 Leo McCormack |
| 3 | + * |
| 4 | + * Permission to use, copy, modify, and/or distribute this software for any |
| 5 | + * purpose with or without fee is hereby granted, provided that the above |
| 6 | + * copyright notice and this permission notice appear in all copies. |
| 7 | + * |
| 8 | + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH |
| 9 | + * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
| 10 | + * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, |
| 11 | + * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM |
| 12 | + * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR |
| 13 | + * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
| 14 | + * PERFORMANCE OF THIS SOFTWARE. |
| 15 | + */ |
| 16 | + |
| 17 | +/** |
| 18 | + * @file tvconv.h |
| 19 | + * @brief A time-varying multi-channel convolver |
| 20 | + * @author Rapolas Daugintis |
| 21 | + * @date 13.07.2021 |
| 22 | + */ |
| 23 | + |
| 24 | +#ifndef __TVCONV_H_INCLUDED__ |
| 25 | +#define __TVCONV_H_INCLUDED__ |
| 26 | + |
| 27 | +#include "_common.h" |
| 28 | + |
| 29 | +#ifdef __cplusplus |
| 30 | +extern "C" { |
| 31 | +#endif /* __cplusplus */ |
| 32 | + |
| 33 | +/* ========================================================================== */ |
| 34 | +/* Main Functions */ |
| 35 | +/* ========================================================================== */ |
| 36 | + |
| 37 | +/** |
| 38 | + * Creates an instance of tvconv |
| 39 | + * |
| 40 | + * @param[in] phTVCnv (&) address of tvconv handle |
| 41 | + */ |
| 42 | +void tvconv_create(void** const phTVCnv); |
| 43 | + |
| 44 | +/** |
| 45 | + * Destroys an instance of tvconv |
| 46 | + * |
| 47 | + * @param[in] phTVCnv (&) address of tvconv handle |
| 48 | + */ |
| 49 | +void tvconv_destroy(void** const phTVCnv); |
| 50 | + |
| 51 | +/** |
| 52 | + * Initialises an instance of tvconv with default settings |
| 53 | + * |
| 54 | + * @param[in] hTVCnv tvconv handle |
| 55 | + * @param[in] samplerate Host samplerate. |
| 56 | + * @param[in] hostBlockSize Host frame/block size |
| 57 | + */ |
| 58 | +void tvconv_init(void* const hTVCnv, |
| 59 | + int samplerate, |
| 60 | + int hostBlockSize); |
| 61 | + |
| 62 | +/** |
| 63 | + * Performs the time-varying convolution processing |
| 64 | + * |
| 65 | + * @param[in] hTVCnv tvconv handle |
| 66 | + * @param[in] inputs Input channel buffers; 2-D array: nInputs x nSamples |
| 67 | + * @param[in] outputs Output channel buffers; 2-D array: nOutputs x nSamples |
| 68 | + * @param[in] nInputs Number of input channels |
| 69 | + * @param[in] nOutputs Number of output channels |
| 70 | + * @param[in] nSamples Number of samples in 'inputs'/'output' matrices (block size) |
| 71 | + */ |
| 72 | +void tvconv_process(void* const hTVCnv, |
| 73 | + float** const inputs, |
| 74 | + float** const outputs, |
| 75 | + int nInputs, |
| 76 | + int nOutputs, |
| 77 | + int nSamples); |
| 78 | + |
| 79 | + |
| 80 | +/* ========================================================================== */ |
| 81 | +/* Set Functions */ |
| 82 | +/* ========================================================================== */ |
| 83 | + |
| 84 | +/** |
| 85 | + * Sets all intialisation flags to 1. Re-initialising all settings/variables, |
| 86 | + * as tvconv is currently configured, at next available opportunity. |
| 87 | + */ |
| 88 | +void tvconv_refreshParams(void* const hTVCnv); |
| 89 | + |
| 90 | +/** |
| 91 | + * Checks whether things have to be reinitialised, and does so if it is needed |
| 92 | + */ |
| 93 | +void tvconv_checkReInit(void* const hTVCnv); |
| 94 | + |
| 95 | +/** Reads IRs and positions from the current sofa file path. */ |
| 96 | +void tvconv_setFiltersAndPositions(void* const hTVCnv); |
| 97 | + |
| 98 | +/** Sets current sofa file path. */ |
| 99 | +void tvconv_setSofaFilePath(void* const hTVCnv, const char* path); |
| 100 | + |
| 101 | +/** |
| 102 | + * Sets the target listener position. |
| 103 | + * |
| 104 | + * @param[in] dim dimension of the coordinate to be set (0 is x, 1 is y, |
| 105 | + * * and 2 is z). |
| 106 | + * @param[in] position new position to be set. |
| 107 | + */ |
| 108 | +void tvconv_setTargetPosition(void* const hTVCnv, float position, int dim); |
| 109 | + |
| 110 | + |
| 111 | +/* ========================================================================== */ |
| 112 | +/* Get Functions */ |
| 113 | +/* ========================================================================== */ |
| 114 | + |
| 115 | +/** |
| 116 | + * Returns the processing framesize (i.e., number of samples processed with |
| 117 | + * every _process() call ) |
| 118 | + */ |
| 119 | +int tvconv_getFrameSize(void); |
| 120 | + |
| 121 | + |
| 122 | +/** Returns the number input channels */ |
| 123 | +int tvconv_getNumInputChannels(void* const hTVCnv); |
| 124 | + |
| 125 | +/** |
| 126 | + * Returns the number of output channels (the same as the number of channels in |
| 127 | + * the loaded sofa file) |
| 128 | + */ |
| 129 | +int tvconv_getNumOutputChannels(void* const hTVCnv); |
| 130 | + |
| 131 | +/** Returns the currect host block size */ |
| 132 | +int tvconv_getHostBlockSize(void* const hTVCnv); |
| 133 | + |
| 134 | +/** Returns the number of IR channels in the loaded sofa file */ |
| 135 | +int tvconv_getNumIRs(void* const hTVCnv); |
| 136 | + |
| 137 | +/** Returns the number of listener positions in the loaded sofa file */ |
| 138 | +int tvconv_getNumListenerPositions(void* const hTVCnv); |
| 139 | + |
| 140 | +/** Returns the current coordinate of dimension dim (0 ... NUM_DIMENSIONS-1) */ |
| 141 | +float tvconv_getListenerPosition(void* const hTVCnv, int index, int dim); |
| 142 | + |
| 143 | +/** Returns the index of the current IR position */ |
| 144 | +int tvconv_getListenerPositionIdx(void* const hTVCnv); |
| 145 | + |
| 146 | +/** Returns the current coordinate of dimension dim (0 ... NUM_DIMENSIONS-1) */ |
| 147 | +float tvconv_getTargetPosition(void* const hTVCnv, int dim); |
| 148 | + |
| 149 | +/** Returns the source coordinate of dimension dim (0 ... NUM_DIMENSIONS-1) */ |
| 150 | +float tvconv_getSourcePosition(void* const hTVCnv, int dim); |
| 151 | + |
| 152 | +/** Returns minimum cooridinate of dimension dim (0 ... NUM_DIMENSIONS-1) */ |
| 153 | +float tvconv_getMinDimension(void* const hTVCnv, int dim); |
| 154 | + |
| 155 | +/** Returns minimum cooridinate of dimension dim (0 ... NUM_DIMENSIONS-1) */ |
| 156 | +float tvconv_getMaxDimension(void* const hTVCnv, int dim); |
| 157 | + |
| 158 | +/** Returns the current filter length, in samples */ |
| 159 | +int tvconv_getIRLength(void* const hTVCnv); |
| 160 | + |
| 161 | +/** Returns the samplerate of the loaded filters */ |
| 162 | +int tvconv_getIRFs(void* const hTVCnv); |
| 163 | + |
| 164 | +/** Returns the samperate of the host */ |
| 165 | +int tvconv_getHostFs(void* const hTVCnv); |
| 166 | + |
| 167 | +/** |
| 168 | + * Returns the processing delay in samples (may be used for delay compensation |
| 169 | + * features) |
| 170 | + */ |
| 171 | +int tvconv_getProcessingDelay(void* const hTVCnv); |
| 172 | + |
| 173 | +/** Returns the current Sofa file path */ |
| 174 | +char* tvconv_getSofaFilePath(void* const hTVCnv); |
| 175 | + |
| 176 | +/** Returns current codec status (see #CODEC_STATUS enum) */ |
| 177 | +CODEC_STATUS tvconv_getCodecStatus(void* const hTVCnv); |
| 178 | + |
| 179 | + |
| 180 | +#ifdef __cplusplus |
| 181 | +} /* extern "C" { */ |
| 182 | +#endif /* __cplusplus */ |
| 183 | + |
| 184 | +#endif /* __TVCONV_H_INCLUDED__ */ |
0 commit comments