Home | History | Annotate | Download | only in media
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef ANDROID_EFFECTSFACTORYAPI_H_
     18 #define ANDROID_EFFECTSFACTORYAPI_H_
     19 
     20 #include <errno.h>
     21 #include <stdint.h>
     22 #include <sys/types.h>
     23 #include <hardware/audio_effect.h>
     24 
     25 #if __cplusplus
     26 extern "C" {
     27 #endif
     28 
     29 /////////////////////////////////////////////////
     30 //      Effect factory interface
     31 /////////////////////////////////////////////////
     32 
     33 ////////////////////////////////////////////////////////////////////////////////
     34 //
     35 //    Function:       EffectQueryNumberEffects
     36 //
     37 //    Description:    Returns the number of different effects in all loaded libraries.
     38 //          Each effect must have a different effect uuid (see
     39 //          effect_descriptor_t). This function together with EffectQueryEffect()
     40 //          is used to enumerate all effects present in all loaded libraries.
     41 //          Each time EffectQueryNumberEffects() is called, the factory must
     42 //          reset the index of the effect descriptor returned by next call to
     43 //          EffectQueryEffect() to restart enumeration from the beginning.
     44 //
     45 //    Input/Output:
     46 //          pNumEffects:    address where the number of effects should be returned.
     47 //
     48 //    Output:
     49 //        returned value:    0          successful operation.
     50 //                          -ENODEV     factory failed to initialize
     51 //                          -EINVAL     invalid pNumEffects
     52 //        *pNumEffects:     updated with number of effects in factory
     53 //
     54 ////////////////////////////////////////////////////////////////////////////////
     55 int EffectQueryNumberEffects(uint32_t *pNumEffects);
     56 
     57 ////////////////////////////////////////////////////////////////////////////////
     58 //
     59 //    Function:       EffectQueryEffect
     60 //
     61 //    Description:    Returns a descriptor of the next available effect.
     62 //          See effect_descriptor_t for a details on effect descriptor.
     63 //          This function together with EffectQueryNumberEffects() is used to enumerate all
     64 //          effects present in all loaded libraries. The enumeration sequence is:
     65 //              EffectQueryNumberEffects(&num_effects);
     66 //              for (i = 0; i < num_effects; i++)
     67 //                  EffectQueryEffect(i,...);
     68 //
     69 //    Input/Output:
     70 //          pDescriptor:    address where to return the effect descriptor.
     71 //
     72 //    Output:
     73 //        returned value:    0          successful operation.
     74 //                          -ENOENT     no more effect available
     75 //                          -ENODEV     factory failed to initialize
     76 //                          -EINVAL     invalid pDescriptor
     77 //                          -ENOSYS     effect list has changed since last execution of EffectQueryNumberEffects()
     78 //        *pDescriptor:     updated with the effect descriptor.
     79 //
     80 ////////////////////////////////////////////////////////////////////////////////
     81 int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor);
     82 
     83 ////////////////////////////////////////////////////////////////////////////////
     84 //
     85 //    Function:       EffectCreate
     86 //
     87 //    Description:    Creates an effect engine of the specified type and returns an
     88 //          effect control interface on this engine. The function will allocate the
     89 //          resources for an instance of the requested effect engine and return
     90 //          a handler on the effect control interface.
     91 //
     92 //    Input:
     93 //          pEffectUuid:    pointer to the effect uuid.
     94 //          sessionId:  audio session to which this effect instance will be attached. All effects created
     95 //              with the same session ID are connected in series and process the same signal stream.
     96 //              Knowing that two effects are part of the same effect chain can help the library implement
     97 //              some kind of optimizations.
     98 //          ioId:   identifies the output or input stream this effect is directed to at audio HAL. For future
     99 //              use especially with tunneled HW accelerated effects
    100 //
    101 //    Input/Output:
    102 //          pHandle:        address where to return the effect handle.
    103 //
    104 //    Output:
    105 //        returned value:    0          successful operation.
    106 //                          -ENODEV     factory failed to initialize
    107 //                          -EINVAL     invalid pEffectUuid or pHandle
    108 //                          -ENOENT     no effect with this uuid found
    109 //        *pHandle:         updated with the effect handle.
    110 //
    111 ////////////////////////////////////////////////////////////////////////////////
    112 int EffectCreate(effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, effect_handle_t *pHandle);
    113 
    114 ////////////////////////////////////////////////////////////////////////////////
    115 //
    116 //    Function:       EffectRelease
    117 //
    118 //    Description:    Releases the effect engine whose handler is given as argument.
    119 //          All resources allocated to this particular instance of the effect are
    120 //          released.
    121 //
    122 //    Input:
    123 //          handle:    handler on the effect interface to be released.
    124 //
    125 //    Output:
    126 //        returned value:    0          successful operation.
    127 //                          -ENODEV     factory failed to initialize
    128 //                          -EINVAL     invalid interface handler
    129 //
    130 ////////////////////////////////////////////////////////////////////////////////
    131 int EffectRelease(effect_handle_t handle);
    132 
    133 ////////////////////////////////////////////////////////////////////////////////
    134 //
    135 //    Function:       EffectGetDescriptor
    136 //
    137 //    Description:    Returns the descriptor of the effect which uuid is pointed
    138 //          to by first argument.
    139 //
    140 //    Input:
    141 //          pEffectUuid:    pointer to the effect uuid.
    142 //
    143 //    Input/Output:
    144 //          pDescriptor:    address where to return the effect descriptor.
    145 //
    146 //    Output:
    147 //        returned value:    0          successful operation.
    148 //                          -ENODEV     factory failed to initialize
    149 //                          -EINVAL     invalid pEffectUuid or pDescriptor
    150 //                          -ENOENT     no effect with this uuid found
    151 //        *pDescriptor:     updated with the effect descriptor.
    152 //
    153 ////////////////////////////////////////////////////////////////////////////////
    154 int EffectGetDescriptor(effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor);
    155 
    156 ////////////////////////////////////////////////////////////////////////////////
    157 //
    158 //    Function:       EffectIsNullUuid
    159 //
    160 //    Description:    Helper function to compare effect uuid to EFFECT_UUID_NULL
    161 //
    162 //    Input:
    163 //          pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL.
    164 //
    165 //    Output:
    166 //        returned value:    0 if uuid is different from EFFECT_UUID_NULL.
    167 //                           1 if uuid is equal to EFFECT_UUID_NULL.
    168 //
    169 ////////////////////////////////////////////////////////////////////////////////
    170 int EffectIsNullUuid(effect_uuid_t *pEffectUuid);
    171 
    172 #if __cplusplus
    173 }  // extern "C"
    174 #endif
    175 
    176 
    177 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/
    178