1 /* 2 * Copyright (C) 2004-2010 NXP Software 3 * Copyright (C) 2010 The Android Open Source Project 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /****************************************************************************************/ 19 /* */ 20 /* Header file for the application layer interface of the LVREV module */ 21 /* */ 22 /* This files includes all definitions, types, structures and function prototypes */ 23 /* required by the calling layer. All other types, structures and functions are */ 24 /* private. */ 25 /* */ 26 /****************************************************************************************/ 27 28 #ifndef __LVREV_H__ 29 #define __LVREV_H__ 30 31 /****************************************************************************************/ 32 /* */ 33 /* Includes */ 34 /* */ 35 /****************************************************************************************/ 36 #include "LVM_Types.h" 37 38 /****************************************************************************************/ 39 /* */ 40 /* Definitions */ 41 /* */ 42 /****************************************************************************************/ 43 /* General */ 44 #define LVREV_BLOCKSIZE_MULTIPLE 1 /* Processing block size multiple */ 45 #define LVREV_MAX_T60 7000 /* Maximum decay time is 7000ms */ 46 47 /* Memory table*/ 48 #define LVREV_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 49 50 /****************************************************************************************/ 51 /* */ 52 /* Types */ 53 /* */ 54 /****************************************************************************************/ 55 /* Instance handle */ 56 typedef void *LVREV_Handle_t; 57 58 /* Status return values */ 59 typedef enum 60 { 61 LVREV_SUCCESS = 0, /* Successful return from a routine */ 62 LVREV_NULLADDRESS = 1, /* NULL allocation address */ 63 LVREV_OUTOFRANGE = 2, /* Out of range control parameter */ 64 LVREV_INVALIDNUMSAMPLES = 3, /* Invalid number of samples */ 65 LVREV_RETURNSTATUS_DUMMY = LVM_MAXENUM 66 } LVREV_ReturnStatus_en; 67 68 /* Reverb delay lines */ 69 typedef enum 70 { 71 LVREV_DELAYLINES_1 = 1, /* One delay line */ 72 LVREV_DELAYLINES_2 = 2, /* Two delay lines */ 73 LVREV_DELAYLINES_4 = 4, /* Four delay lines */ 74 LVREV_DELAYLINES_DUMMY = LVM_MAXENUM 75 } LVREV_NumDelayLines_en; 76 77 /****************************************************************************************/ 78 /* */ 79 /* Structures */ 80 /* */ 81 /****************************************************************************************/ 82 83 /* Memory table containing the region definitions */ 84 typedef struct 85 { 86 LVM_MemoryRegion_st Region[LVREV_NR_MEMORY_REGIONS]; /* One definition for each region */ 87 } LVREV_MemoryTable_st; 88 89 /* Control Parameter structure */ 90 typedef struct 91 { 92 /* General parameters */ 93 LVM_Mode_en OperatingMode; /* Operating mode */ 94 LVM_Fs_en SampleRate; /* Sample rate */ 95 LVM_Format_en SourceFormat; /* Source data format */ 96 97 /* Parameters for REV */ 98 LVM_UINT16 Level; /* Level, 0 to 100 representing percentage of reverb */ 99 LVM_UINT32 LPF; /* Low pass filter, in Hz */ 100 LVM_UINT32 HPF; /* High pass filter, in Hz */ 101 102 LVM_UINT16 T60; /* Decay time constant, in ms */ 103 LVM_UINT16 Density; /* Echo density, 0 to 100 for minimum to maximum density */ 104 LVM_UINT16 Damping; /* Damping */ 105 LVM_UINT16 RoomSize; /* Simulated room size, 1 to 100 for minimum to maximum size */ 106 107 } LVREV_ControlParams_st; 108 109 /* Instance Parameter structure */ 110 typedef struct 111 { 112 /* General */ 113 LVM_UINT16 MaxBlockSize; /* Maximum processing block size */ 114 115 /* Reverb */ 116 LVM_Format_en SourceFormat; /* Source data formats to support */ 117 LVREV_NumDelayLines_en NumDelays; /* The number of delay lines, 1, 2 or 4 */ 118 119 } LVREV_InstanceParams_st; 120 121 /****************************************************************************************/ 122 /* */ 123 /* Function Prototypes */ 124 /* */ 125 /****************************************************************************************/ 126 127 /****************************************************************************************/ 128 /* */ 129 /* FUNCTION: LVREV_GetMemoryTable */ 130 /* */ 131 /* DESCRIPTION: */ 132 /* This function is used to obtain the LVREV module memory requirements to support */ 133 /* memory allocation. It can also be used to return the memory base address provided */ 134 /* during memory allocation to support freeing of memory when the LVREV module is no */ 135 /* longer required. It is called in two ways: */ 136 /* */ 137 /* hInstance = NULL Returns the memory requirements */ 138 /* hInstance = Instance handle Returns the memory requirements and allocated */ 139 /* base addresses. */ 140 /* */ 141 /* When this function is called with hInstance = NULL the memory base address pointers */ 142 /* will be NULL on return. */ 143 /* */ 144 /* When the function is called for freeing memory, hInstance = Instance Handle the */ 145 /* memory table returns the allocated memory and base addresses used during */ 146 /* initialisation. */ 147 /* */ 148 /* PARAMETERS: */ 149 /* hInstance Instance Handle */ 150 /* pMemoryTable Pointer to an empty memory table */ 151 /* pInstanceParams Pointer to the instance parameters */ 152 /* */ 153 /* RETURNS: */ 154 /* LVREV_SUCCESS Succeeded */ 155 /* LVREV_NULLADDRESS When pMemoryTable is NULL */ 156 /* LVREV_NULLADDRESS When requesting memory requirements and pInstanceParams */ 157 /* is NULL */ 158 /* */ 159 /* NOTES: */ 160 /* 1. This function may be interrupted by the LVREV_Process function */ 161 /* */ 162 /****************************************************************************************/ 163 LVREV_ReturnStatus_en LVREV_GetMemoryTable(LVREV_Handle_t hInstance, 164 LVREV_MemoryTable_st *pMemoryTable, 165 LVREV_InstanceParams_st *pInstanceParams); 166 167 /****************************************************************************************/ 168 /* */ 169 /* FUNCTION: LVREV_GetInstanceHandle */ 170 /* */ 171 /* DESCRIPTION: */ 172 /* This function is used to create a LVREV module instance. It returns the created */ 173 /* instance handle through phInstance. All parameters are set to invalid values, the */ 174 /* LVREV_SetControlParameters function must be called with a set of valid control */ 175 /* parameters before the LVREV_Process function can be called. */ 176 /* */ 177 /* The memory allocation must be provided by the application by filling in the memory */ 178 /* region base addresses in the memory table before calling this function. */ 179 /* */ 180 /* PARAMETERS: */ 181 /* phInstance Pointer to the instance handle */ 182 /* pMemoryTable Pointer to the memory definition table */ 183 /* pInstanceParams Pointer to the instance parameters */ 184 /* */ 185 /* RETURNS: */ 186 /* LVREV_SUCCESS Succeeded */ 187 /* LVREV_NULLADDRESS When phInstance or pMemoryTable or pInstanceParams is NULL */ 188 /* LVREV_NULLADDRESS When one of the memory regions has a NULL pointer */ 189 /* */ 190 /* NOTES: */ 191 /* */ 192 /****************************************************************************************/ 193 LVREV_ReturnStatus_en LVREV_GetInstanceHandle(LVREV_Handle_t *phInstance, 194 LVREV_MemoryTable_st *pMemoryTable, 195 LVREV_InstanceParams_st *pInstanceParams); 196 197 /****************************************************************************************/ 198 /* */ 199 /* FUNCTION: LVXX_GetControlParameters */ 200 /* */ 201 /* DESCRIPTION: */ 202 /* Request the LVREV module control parameters. The current parameter set is returned */ 203 /* via the parameter pointer. */ 204 /* */ 205 /* PARAMETERS: */ 206 /* hInstance Instance handle */ 207 /* pControlParams Pointer to an empty parameter structure */ 208 /* */ 209 /* RETURNS: */ 210 /* LVREV_SUCCESS Succeeded */ 211 /* LVREV_NULLADDRESS When hInstance or pControlParams is NULL */ 212 /* */ 213 /* NOTES: */ 214 /* 1. This function may be interrupted by the LVREV_Process function */ 215 /* */ 216 /****************************************************************************************/ 217 LVREV_ReturnStatus_en LVREV_GetControlParameters(LVREV_Handle_t hInstance, 218 LVREV_ControlParams_st *pControlParams); 219 220 /****************************************************************************************/ 221 /* */ 222 /* FUNCTION: LVREV_SetControlParameters */ 223 /* */ 224 /* DESCRIPTION: */ 225 /* Sets or changes the LVREV module parameters. */ 226 /* */ 227 /* PARAMETERS: */ 228 /* hInstance Instance handle */ 229 /* pNewParams Pointer to a parameter structure */ 230 /* */ 231 /* RETURNS: */ 232 /* LVREV_SUCCESS Succeeded */ 233 /* LVREV_NULLADDRESS When hInstance or pNewParams is NULL */ 234 /* */ 235 /* NOTES: */ 236 /* 1. This function may be interrupted by the LVREV_Process function */ 237 /* */ 238 /****************************************************************************************/ 239 LVREV_ReturnStatus_en LVREV_SetControlParameters(LVREV_Handle_t hInstance, 240 LVREV_ControlParams_st *pNewParams); 241 242 /****************************************************************************************/ 243 /* */ 244 /* FUNCTION: LVREV_ClearAudioBuffers */ 245 /* */ 246 /* DESCRIPTION: */ 247 /* This function is used to clear the internal audio buffers of the module. */ 248 /* */ 249 /* PARAMETERS: */ 250 /* hInstance Instance handle */ 251 /* */ 252 /* RETURNS: */ 253 /* LVREV_SUCCESS Initialisation succeeded */ 254 /* LVREV_NULLADDRESS Instance is NULL */ 255 /* */ 256 /* NOTES: */ 257 /* 1. This function must not be interrupted by the LVREV_Process function */ 258 /* */ 259 /****************************************************************************************/ 260 LVREV_ReturnStatus_en LVREV_ClearAudioBuffers(LVREV_Handle_t hInstance); 261 262 /****************************************************************************************/ 263 /* */ 264 /* FUNCTION: LVREV_Process */ 265 /* */ 266 /* DESCRIPTION: */ 267 /* Process function for the LVREV module. */ 268 /* */ 269 /* PARAMETERS: */ 270 /* hInstance Instance handle */ 271 /* pInData Pointer to the input data */ 272 /* pOutData Pointer to the output data */ 273 /* NumSamples Number of samples in the input buffer */ 274 /* */ 275 /* RETURNS: */ 276 /* LVREV_SUCCESS Succeeded */ 277 /* LVREV_INVALIDNUMSAMPLES NumSamples was larger than the maximum block size */ 278 /* */ 279 /* NOTES: */ 280 /* 1. The input and output buffers must be 32-bit aligned */ 281 /* */ 282 /****************************************************************************************/ 283 LVREV_ReturnStatus_en LVREV_Process(LVREV_Handle_t hInstance, 284 const LVM_FLOAT *pInData, 285 LVM_FLOAT *pOutData, 286 const LVM_UINT16 NumSamples); 287 288 #endif /* __LVREV_H__ */ 289 290 /* End of file */ 291