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
     78 //                                      EffectQueryNumberEffects()
     79 //        *pDescriptor:     updated with the effect descriptor.
     80 //
     81 ////////////////////////////////////////////////////////////////////////////////
     82 int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor);
     83 
     84 ////////////////////////////////////////////////////////////////////////////////
     85 //
     86 //    Function:       EffectCreate
     87 //
     88 //    Description:    Creates an effect engine of the specified type and returns an
     89 //          effect control interface on this engine. The function will allocate the
     90 //          resources for an instance of the requested effect engine and return
     91 //          a handle on the effect control interface.
     92 //
     93 //    Input:
     94 //          pEffectUuid:    pointer to the effect uuid.
     95 //          sessionId:  audio session to which this effect instance will be attached. All effects
     96 //              created with the same session ID are connected in series and process the same signal
     97 //              stream.  Knowing that two effects are part of the same effect chain can help the
     98 //              library implement some kind of optimizations.
     99 //          ioId:   identifies the output or input stream this effect is directed to at audio HAL.
    100 //              For future use especially with tunneled HW accelerated effects
    101 //
    102 //    Input/Output:
    103 //          pHandle:        address where to return the effect handle.
    104 //
    105 //    Output:
    106 //        returned value:    0          successful operation.
    107 //                          -ENODEV     factory failed to initialize
    108 //                          -EINVAL     invalid pEffectUuid or pHandle
    109 //                          -ENOENT     no effect with this uuid found
    110 //        *pHandle:         updated with the effect handle.
    111 //
    112 ////////////////////////////////////////////////////////////////////////////////
    113 int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId,
    114         effect_handle_t *pHandle);
    115 
    116 ////////////////////////////////////////////////////////////////////////////////
    117 //
    118 //    Function:       EffectRelease
    119 //
    120 //    Description:    Releases the effect engine whose handle is given as argument.
    121 //          All resources allocated to this particular instance of the effect are
    122 //          released.
    123 //
    124 //    Input:
    125 //          handle:    handle on the effect interface to be released.
    126 //
    127 //    Output:
    128 //        returned value:    0          successful operation.
    129 //                          -ENODEV     factory failed to initialize
    130 //                          -EINVAL     invalid interface handle
    131 //
    132 ////////////////////////////////////////////////////////////////////////////////
    133 int EffectRelease(effect_handle_t handle);
    134 
    135 ////////////////////////////////////////////////////////////////////////////////
    136 //
    137 //    Function:       EffectGetDescriptor
    138 //
    139 //    Description:    Returns the descriptor of the effect which uuid is pointed
    140 //          to by first argument.
    141 //
    142 //    Input:
    143 //          pEffectUuid:    pointer to the effect uuid.
    144 //
    145 //    Input/Output:
    146 //          pDescriptor:    address where to return the effect descriptor.
    147 //
    148 //    Output:
    149 //        returned value:    0          successful operation.
    150 //                          -ENODEV     factory failed to initialize
    151 //                          -EINVAL     invalid pEffectUuid or pDescriptor
    152 //                          -ENOENT     no effect with this uuid found
    153 //        *pDescriptor:     updated with the effect descriptor.
    154 //
    155 ////////////////////////////////////////////////////////////////////////////////
    156 int EffectGetDescriptor(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor);
    157 
    158 ////////////////////////////////////////////////////////////////////////////////
    159 //
    160 //    Function:       EffectIsNullUuid
    161 //
    162 //    Description:    Helper function to compare effect uuid to EFFECT_UUID_NULL
    163 //
    164 //    Input:
    165 //          pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL.
    166 //
    167 //    Output:
    168 //        returned value:    0 if uuid is different from EFFECT_UUID_NULL.
    169 //                           1 if uuid is equal to EFFECT_UUID_NULL.
    170 //
    171 ////////////////////////////////////////////////////////////////////////////////
    172 int EffectIsNullUuid(const effect_uuid_t *pEffectUuid);
    173 
    174 int EffectDumpEffects(int fd);
    175 
    176 #if __cplusplus
    177 }  // extern "C"
    178 #endif
    179 
    180 
    181 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/
    182