michael@0: /* michael@0: * Copyright (C) 2010 The Android Open Source Project michael@0: * michael@0: * Licensed under the Apache License, Version 2.0 (the "License"); michael@0: * you may not use this file except in compliance with the License. michael@0: * You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, software michael@0: * distributed under the License is distributed on an "AS IS" BASIS, michael@0: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. michael@0: * See the License for the specific language governing permissions and michael@0: * limitations under the License. michael@0: */ michael@0: michael@0: #ifndef ANDROID_EFFECTAPI_H_ michael@0: #define ANDROID_EFFECTAPI_H_ michael@0: michael@0: #include michael@0: #include michael@0: #include michael@0: michael@0: #if __cplusplus michael@0: extern "C" { michael@0: #endif michael@0: michael@0: ///////////////////////////////////////////////// michael@0: // Effect control interface michael@0: ///////////////////////////////////////////////// michael@0: michael@0: // The effect control interface is exposed by each effect engine implementation. It consists of michael@0: // a set of functions controlling the configuration, activation and process of the engine. michael@0: // The functions are grouped in a structure of type effect_interface_s: michael@0: // struct effect_interface_s { michael@0: // effect_process_t process; michael@0: // effect_command_t command; michael@0: // }; michael@0: michael@0: michael@0: // effect_interface_t: Effect control interface handle. michael@0: // The effect_interface_t serves two purposes regarding the implementation of the effect engine: michael@0: // - 1 it is the address of a pointer to an effect_interface_s structure where the functions michael@0: // of the effect control API for a particular effect are located. michael@0: // - 2 it is the address of the context of a particular effect instance. michael@0: // A typical implementation in the effect library would define a structure as follows: michael@0: // struct effect_module_s { michael@0: // const struct effect_interface_s *itfe; michael@0: // effect_config_t config; michael@0: // effect_context_t context; michael@0: // } michael@0: // The implementation of EffectCreate() function would then allocate a structure of this michael@0: // type and return its address as effect_interface_t michael@0: typedef struct effect_interface_s **effect_interface_t; michael@0: michael@0: michael@0: // Effect API version 1.0 michael@0: #define EFFECT_API_VERSION 0x0100 // Format 0xMMmm MM: Major version, mm: minor version michael@0: michael@0: // Maximum length of character strings in structures defines by this API. michael@0: #define EFFECT_STRING_LEN_MAX 64 michael@0: michael@0: // michael@0: //--- Effect descriptor structure effect_descriptor_t michael@0: // michael@0: michael@0: // Unique effect ID (can be generated from the following site: michael@0: // http://www.itu.int/ITU-T/asn1/uuid.html) michael@0: // This format is used for both "type" and "uuid" fields of the effect descriptor structure. michael@0: // - When used for effect type and the engine is implementing and effect corresponding to a standard michael@0: // OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface. michael@0: // - When used as uuid, it should be a unique UUID for this particular implementation. michael@0: typedef struct effect_uuid_s { michael@0: uint32_t timeLow; michael@0: uint16_t timeMid; michael@0: uint16_t timeHiAndVersion; michael@0: uint16_t clockSeq; michael@0: uint8_t node[6]; michael@0: } effect_uuid_t; michael@0: michael@0: // NULL UUID definition (matches SL_IID_NULL_) michael@0: #define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \ michael@0: { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } } michael@0: static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER; michael@0: const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_; michael@0: const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210"; michael@0: michael@0: // The effect descriptor contains necessary information to facilitate the enumeration of the effect michael@0: // engines present in a library. michael@0: typedef struct effect_descriptor_s { michael@0: effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect michael@0: effect_uuid_t uuid; // UUID for this particular implementation michael@0: uint16_t apiVersion; // Version of the effect API implemented: matches EFFECT_API_VERSION michael@0: uint32_t flags; // effect engine capabilities/requirements flags (see below) michael@0: uint16_t cpuLoad; // CPU load indication (see below) michael@0: uint16_t memoryUsage; // Data Memory usage (see below) michael@0: char name[EFFECT_STRING_LEN_MAX]; // human readable effect name michael@0: char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name michael@0: } effect_descriptor_t; michael@0: michael@0: // CPU load and memory usage indication: each effect implementation must provide an indication of michael@0: // its CPU and memory usage for the audio effect framework to limit the number of effects michael@0: // instantiated at a given time on a given platform. michael@0: // The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS. michael@0: // The memory usage is expressed in KB and includes only dynamically allocated memory michael@0: michael@0: // Definitions for flags field of effect descriptor. michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | description | bits | values michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | connection mode | 0..1 | 0 insert: after track process michael@0: // | | | 1 auxiliary: connect to track auxiliary michael@0: // | | | output and use send level michael@0: // | | | 2 replace: replaces track process function; michael@0: // | | | must implement SRC, volume and mono to stereo. michael@0: // | | | 3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | insertion preference | 2..4 | 0 none michael@0: // | | | 1 first of the chain michael@0: // | | | 2 last of the chain michael@0: // | | | 3 exclusive (only effect in the insert chain) michael@0: // | | | 4..7 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Volume management | 5..6 | 0 none michael@0: // | | | 1 implements volume control michael@0: // | | | 2 requires volume indication michael@0: // | | | 3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Device indication | 7..8 | 0 none michael@0: // | | | 1 requires device updates michael@0: // | | | 2..3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Sample input mode | 9..10 | 0 direct: process() function or EFFECT_CMD_CONFIGURE michael@0: // | | | command must specify a buffer descriptor michael@0: // | | | 1 provider: process() function uses the michael@0: // | | | bufferProvider indicated by the michael@0: // | | | EFFECT_CMD_CONFIGURE command to request input. michael@0: // | | | buffers. michael@0: // | | | 2 both: both input modes are supported michael@0: // | | | 3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Sample output mode | 11..12 | 0 direct: process() function or EFFECT_CMD_CONFIGURE michael@0: // | | | command must specify a buffer descriptor michael@0: // | | | 1 provider: process() function uses the michael@0: // | | | bufferProvider indicated by the michael@0: // | | | EFFECT_CMD_CONFIGURE command to request output michael@0: // | | | buffers. michael@0: // | | | 2 both: both output modes are supported michael@0: // | | | 3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Hardware acceleration | 13..15 | 0 No hardware acceleration michael@0: // | | | 1 non tunneled hw acceleration: the process() function michael@0: // | | | reads the samples, send them to HW accelerated michael@0: // | | | effect processor, reads back the processed samples michael@0: // | | | and returns them to the output buffer. michael@0: // | | | 2 tunneled hw acceleration: the process() function is michael@0: // | | | transparent. The effect interface is only used to michael@0: // | | | control the effect engine. This mode is relevant for michael@0: // | | | global effects actually applied by the audio michael@0: // | | | hardware on the output stream. michael@0: // +---------------------------+-----------+----------------------------------- michael@0: // | Audio Mode indication | 16..17 | 0 none michael@0: // | | | 1 requires audio mode updates michael@0: // | | | 2..3 reserved michael@0: // +---------------------------+-----------+----------------------------------- michael@0: michael@0: // Insert mode michael@0: #define EFFECT_FLAG_TYPE_MASK 0x00000003 michael@0: #define EFFECT_FLAG_TYPE_INSERT 0x00000000 michael@0: #define EFFECT_FLAG_TYPE_AUXILIARY 0x00000001 michael@0: #define EFFECT_FLAG_TYPE_REPLACE 0x00000002 michael@0: michael@0: // Insert preference michael@0: #define EFFECT_FLAG_INSERT_MASK 0x0000001C michael@0: #define EFFECT_FLAG_INSERT_ANY 0x00000000 michael@0: #define EFFECT_FLAG_INSERT_FIRST 0x00000004 michael@0: #define EFFECT_FLAG_INSERT_LAST 0x00000008 michael@0: #define EFFECT_FLAG_INSERT_EXCLUSIVE 0x0000000C michael@0: michael@0: michael@0: // Volume control michael@0: #define EFFECT_FLAG_VOLUME_MASK 0x00000060 michael@0: #define EFFECT_FLAG_VOLUME_CTRL 0x00000020 michael@0: #define EFFECT_FLAG_VOLUME_IND 0x00000040 michael@0: #define EFFECT_FLAG_VOLUME_NONE 0x00000000 michael@0: michael@0: // Device indication michael@0: #define EFFECT_FLAG_DEVICE_MASK 0x00000180 michael@0: #define EFFECT_FLAG_DEVICE_IND 0x00000080 michael@0: #define EFFECT_FLAG_DEVICE_NONE 0x00000000 michael@0: michael@0: // Sample input modes michael@0: #define EFFECT_FLAG_INPUT_MASK 0x00000600 michael@0: #define EFFECT_FLAG_INPUT_DIRECT 0x00000000 michael@0: #define EFFECT_FLAG_INPUT_PROVIDER 0x00000200 michael@0: #define EFFECT_FLAG_INPUT_BOTH 0x00000400 michael@0: michael@0: // Sample output modes michael@0: #define EFFECT_FLAG_OUTPUT_MASK 0x00001800 michael@0: #define EFFECT_FLAG_OUTPUT_DIRECT 0x00000000 michael@0: #define EFFECT_FLAG_OUTPUT_PROVIDER 0x00000800 michael@0: #define EFFECT_FLAG_OUTPUT_BOTH 0x00001000 michael@0: michael@0: // Hardware acceleration mode michael@0: #define EFFECT_FLAG_HW_ACC_MASK 0x00006000 michael@0: #define EFFECT_FLAG_HW_ACC_SIMPLE 0x00002000 michael@0: #define EFFECT_FLAG_HW_ACC_TUNNEL 0x00004000 michael@0: michael@0: // Audio mode indication michael@0: #define EFFECT_FLAG_AUDIO_MODE_MASK 0x00018000 michael@0: #define EFFECT_FLAG_AUDIO_MODE_IND 0x00008000 michael@0: #define EFFECT_FLAG_AUDIO_MODE_NONE 0x00000000 michael@0: michael@0: // Forward definition of type audio_buffer_t michael@0: typedef struct audio_buffer_s audio_buffer_t; michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: process michael@0: // michael@0: // Description: Effect process function. Takes input samples as specified michael@0: // (count and location) in input buffer descriptor and output processed michael@0: // samples as specified in output buffer descriptor. If the buffer descriptor michael@0: // is not specified the function must use either the buffer or the michael@0: // buffer provider function installed by the EFFECT_CMD_CONFIGURE command. michael@0: // The effect framework will call the process() function after the EFFECT_CMD_ENABLE michael@0: // command is received and until the EFFECT_CMD_DISABLE is received. When the engine michael@0: // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully michael@0: // and when done indicate that it is OK to stop calling the process() function by michael@0: // returning the -ENODATA status. michael@0: // michael@0: // NOTE: the process() function implementation should be "real-time safe" that is michael@0: // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, michael@0: // pthread_cond_wait/pthread_mutex_lock... michael@0: // michael@0: // Input: michael@0: // effect_interface_t: handle to the effect interface this function michael@0: // is called on. michael@0: // inBuffer: buffer descriptor indicating where to read samples to process. michael@0: // If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command. michael@0: // michael@0: // inBuffer: buffer descriptor indicating where to write processed samples. michael@0: // If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command. michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation michael@0: // -ENODATA the engine has finished the disable phase and the framework michael@0: // can stop calling process() michael@0: // -EINVAL invalid interface handle or michael@0: // invalid input/output buffer description michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_process_t)(effect_interface_t self, michael@0: audio_buffer_t *inBuffer, michael@0: audio_buffer_t *outBuffer); michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: command michael@0: // michael@0: // Description: Send a command and receive a response to/from effect engine. michael@0: // michael@0: // Input: michael@0: // effect_interface_t: handle to the effect interface this function michael@0: // is called on. michael@0: // cmdCode: command code: the command can be a standardized command defined in michael@0: // effect_command_e (see below) or a proprietary command. michael@0: // cmdSize: size of command in bytes michael@0: // pCmdData: pointer to command data michael@0: // pReplyData: pointer to reply data michael@0: // michael@0: // Input/Output: michael@0: // replySize: maximum size of reply data as input michael@0: // actual size of reply data as output michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation michael@0: // -EINVAL invalid interface handle or michael@0: // invalid command/reply size or format according to command code michael@0: // The return code should be restricted to indicate problems related to the this michael@0: // API specification. Status related to the execution of a particular command should be michael@0: // indicated as part of the reply field. michael@0: // michael@0: // *pReplyData updated with command response michael@0: // michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_command_t)(effect_interface_t self, michael@0: uint32_t cmdCode, michael@0: uint32_t cmdSize, michael@0: void *pCmdData, michael@0: uint32_t *replySize, michael@0: void *pReplyData); michael@0: michael@0: michael@0: // Effect control interface definition michael@0: struct effect_interface_s { michael@0: effect_process_t process; michael@0: effect_command_t command; michael@0: }; michael@0: michael@0: michael@0: // michael@0: //--- Standardized command codes for command() function michael@0: // michael@0: enum effect_command_e { michael@0: EFFECT_CMD_INIT, // initialize effect engine michael@0: EFFECT_CMD_CONFIGURE, // configure effect engine (see effect_config_t) michael@0: EFFECT_CMD_RESET, // reset effect engine michael@0: EFFECT_CMD_ENABLE, // enable effect process michael@0: EFFECT_CMD_DISABLE, // disable effect process michael@0: EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t) michael@0: EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred michael@0: EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred michael@0: EFFECT_CMD_GET_PARAM, // get parameter michael@0: EFFECT_CMD_SET_DEVICE, // set audio device (see audio_device_e) michael@0: EFFECT_CMD_SET_VOLUME, // set volume michael@0: EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...) michael@0: EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code michael@0: }; michael@0: michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_INIT michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Initialize effect engine: All configurations return to default michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_CONFIGURE michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Apply new audio parameters configurations for input and output buffers michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(effect_config_t) michael@0: // data: effect_config_t michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_RESET michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Reset the effect engine. Keep configuration but resets state and buffer content michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_ENABLE michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Enable the process. Called by the framework before the first call to process() michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_DISABLE michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Disable the process. Called by the framework after the last call to process() michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_PARAM michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Set a parameter and apply it immediately michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(effect_param_t) + size of param and value michael@0: // data: effect_param_t + param + value. See effect_param_t definition below for value offset michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_PARAM_DEFERRED michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(effect_param_t) + size of param and value michael@0: // data: effect_param_t + param + value. See effect_param_t definition below for value offset michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_PARAM_COMMIT michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(int) michael@0: // data: status michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_GET_PARAM michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Get a parameter value michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(effect_param_t) + size of param michael@0: // data: effect_param_t + param michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: sizeof(effect_param_t) + size of param and value michael@0: // data: effect_param_t + param + value. See effect_param_t definition below for value offset michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_DEVICE michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Set the rendering device the audio output path is connected to. See audio_device_e for device michael@0: // values. michael@0: // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this michael@0: // command when the device changes michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(uint32_t) michael@0: // data: audio_device_e michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_VOLUME michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Set and get volume. Used by audio framework to delegate volume control to effect engine. michael@0: // The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in michael@0: // its descriptor to receive this command before every call to process() function michael@0: // If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return michael@0: // the volume that should be applied before the effect is processed. The overall volume (the volume michael@0: // actually applied by the effect engine multiplied by the returned value) should match the value michael@0: // indicated in the command. michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: n * sizeof(uint32_t) michael@0: // data: volume for each channel defined in effect_config_t for output buffer expressed in michael@0: // 8.24 fixed point format michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: n * sizeof(uint32_t) / 0 michael@0: // data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor: michael@0: // volume for each channel defined in effect_config_t for output buffer expressed in michael@0: // 8.24 fixed point format michael@0: // - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor: michael@0: // N/A michael@0: // It is legal to receive a null pointer as pReplyData in which case the effect framework has michael@0: // delegated volume control to another effect michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_SET_AUDIO_MODE michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its michael@0: // descriptor to receive this command when the audio mode changes. michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // command format: michael@0: // size: sizeof(uint32_t) michael@0: // data: audio_mode_e michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // reply format: michael@0: // size: 0 michael@0: // data: N/A michael@0: //================================================================================================== michael@0: // command: EFFECT_CMD_FIRST_PROPRIETARY michael@0: //-------------------------------------------------------------------------------------------------- michael@0: // description: michael@0: // All proprietary effect commands must use command codes above this value. The size and format of michael@0: // command and response fields is free in this case michael@0: //================================================================================================== michael@0: michael@0: michael@0: // Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t michael@0: // structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with michael@0: // regard to the channel mask definition in audio_channels_e e.g : michael@0: // Stereo: left, right michael@0: // 5 point 1: front left, front right, front center, low frequency, back left, back right michael@0: // The buffer size is expressed in frame count, a frame being composed of samples for all michael@0: // channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by michael@0: // definition michael@0: struct audio_buffer_s { michael@0: size_t frameCount; // number of frames in buffer michael@0: union { michael@0: void* raw; // raw pointer to start of buffer michael@0: int32_t* s32; // pointer to signed 32 bit data at start of buffer michael@0: int16_t* s16; // pointer to signed 16 bit data at start of buffer michael@0: uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer michael@0: }; michael@0: }; michael@0: michael@0: // The buffer_provider_s structure contains functions that can be used michael@0: // by the effect engine process() function to query and release input michael@0: // or output audio buffer. michael@0: // The getBuffer() function is called to retrieve a buffer where data michael@0: // should read from or written to by process() function. michael@0: // The releaseBuffer() function MUST be called when the buffer retrieved michael@0: // with getBuffer() is not needed anymore. michael@0: // The process function should use the buffer provider mechanism to retrieve michael@0: // input or output buffer if the inBuffer or outBuffer passed as argument is NULL michael@0: // and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_CONFIGURE michael@0: // command did not specify an audio buffer. michael@0: michael@0: typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer); michael@0: michael@0: typedef struct buffer_provider_s { michael@0: buffer_function_t getBuffer; // retrieve next buffer michael@0: buffer_function_t releaseBuffer; // release used buffer michael@0: void *cookie; // for use by client of buffer provider functions michael@0: } buffer_provider_t; michael@0: michael@0: michael@0: // The buffer_config_s structure specifies the input or output audio format michael@0: // to be used by the effect engine. It is part of the effect_config_t michael@0: // structure that defines both input and output buffer configurations and is michael@0: // passed by the EFFECT_CMD_CONFIGURE command. michael@0: typedef struct buffer_config_s { michael@0: audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly michael@0: uint32_t samplingRate; // sampling rate michael@0: uint32_t channels; // channel mask (see audio_channels_e) michael@0: buffer_provider_t bufferProvider; // buffer provider michael@0: uint8_t format; // Audio format (see audio_format_e) michael@0: uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e) michael@0: uint16_t mask; // indicates which of the above fields is valid michael@0: } buffer_config_t; michael@0: michael@0: // Sample format michael@0: enum audio_format_e { michael@0: SAMPLE_FORMAT_PCM_S15, // PCM signed 16 bits michael@0: SAMPLE_FORMAT_PCM_U8, // PCM unsigned 8 bits michael@0: SAMPLE_FORMAT_PCM_S7_24, // PCM signed 7.24 fixed point representation michael@0: SAMPLE_FORMAT_OTHER // other format (e.g. compressed) michael@0: }; michael@0: michael@0: // Channel mask michael@0: enum audio_channels_e { michael@0: CHANNEL_FRONT_LEFT = 0x1, // front left channel michael@0: CHANNEL_FRONT_RIGHT = 0x2, // front right channel michael@0: CHANNEL_FRONT_CENTER = 0x4, // front center channel michael@0: CHANNEL_LOW_FREQUENCY = 0x8, // low frequency channel michael@0: CHANNEL_BACK_LEFT = 0x10, // back left channel michael@0: CHANNEL_BACK_RIGHT = 0x20, // back right channel michael@0: CHANNEL_FRONT_LEFT_OF_CENTER = 0x40, // front left of center channel michael@0: CHANNEL_FRONT_RIGHT_OF_CENTER = 0x80, // front right of center channel michael@0: CHANNEL_BACK_CENTER = 0x100, // back center channel michael@0: CHANNEL_MONO = CHANNEL_FRONT_LEFT, michael@0: CHANNEL_STEREO = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT), michael@0: CHANNEL_QUAD = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | michael@0: CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT), michael@0: CHANNEL_SURROUND = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | michael@0: CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER), michael@0: CHANNEL_5POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | michael@0: CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT), michael@0: CHANNEL_7POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | michael@0: CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT | michael@0: CHANNEL_FRONT_LEFT_OF_CENTER | CHANNEL_FRONT_RIGHT_OF_CENTER), michael@0: }; michael@0: michael@0: // Render device michael@0: enum audio_device_e { michael@0: DEVICE_EARPIECE = 0x1, // earpiece michael@0: DEVICE_SPEAKER = 0x2, // speaker michael@0: DEVICE_WIRED_HEADSET = 0x4, // wired headset, with microphone michael@0: DEVICE_WIRED_HEADPHONE = 0x8, // wired headphone, without microphone michael@0: DEVICE_BLUETOOTH_SCO = 0x10, // generic bluetooth SCO michael@0: DEVICE_BLUETOOTH_SCO_HEADSET = 0x20, // bluetooth SCO headset michael@0: DEVICE_BLUETOOTH_SCO_CARKIT = 0x40, // bluetooth SCO car kit michael@0: DEVICE_BLUETOOTH_A2DP = 0x80, // generic bluetooth A2DP michael@0: DEVICE_BLUETOOTH_A2DP_HEADPHONES = 0x100, // bluetooth A2DP headphones michael@0: DEVICE_BLUETOOTH_A2DP_SPEAKER = 0x200, // bluetooth A2DP speakers michael@0: DEVICE_AUX_DIGITAL = 0x400, // digital output michael@0: DEVICE_EXTERNAL_SPEAKER = 0x800 // external speaker (stereo and High quality) michael@0: }; michael@0: michael@0: #if ANDROID_VERSION < 17 michael@0: // Audio mode michael@0: enum audio_mode_e { michael@0: AUDIO_MODE_NORMAL, // device idle michael@0: AUDIO_MODE_RINGTONE, // device ringing michael@0: AUDIO_MODE_IN_CALL // audio call connected (VoIP or telephony) michael@0: }; michael@0: #endif michael@0: michael@0: // Values for "accessMode" field of buffer_config_t: michael@0: // overwrite, read only, accumulate (read/modify/write) michael@0: enum effect_buffer_access_e { michael@0: EFFECT_BUFFER_ACCESS_WRITE, michael@0: EFFECT_BUFFER_ACCESS_READ, michael@0: EFFECT_BUFFER_ACCESS_ACCUMULATE michael@0: michael@0: }; michael@0: michael@0: // Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field michael@0: // in buffer_config_t must be taken into account when executing the EFFECT_CMD_CONFIGURE command michael@0: #define EFFECT_CONFIG_BUFFER 0x0001 // buffer field must be taken into account michael@0: #define EFFECT_CONFIG_SMP_RATE 0x0002 // samplingRate field must be taken into account michael@0: #define EFFECT_CONFIG_CHANNELS 0x0004 // channels field must be taken into account michael@0: #define EFFECT_CONFIG_FORMAT 0x0008 // format field must be taken into account michael@0: #define EFFECT_CONFIG_ACC_MODE 0x0010 // accessMode field must be taken into account michael@0: #define EFFECT_CONFIG_PROVIDER 0x0020 // bufferProvider field must be taken into account michael@0: #define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | EFFECT_CONFIG_SMP_RATE | \ michael@0: EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \ michael@0: EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER) michael@0: michael@0: michael@0: // effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_CONFIGURE michael@0: // command to configure audio parameters and buffers for effect engine input and output. michael@0: typedef struct effect_config_s { michael@0: buffer_config_t inputCfg; michael@0: buffer_config_t outputCfg;; michael@0: } effect_config_t; michael@0: michael@0: michael@0: // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM michael@0: // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command. michael@0: // psize and vsize represent the actual size of parameter and value. michael@0: // michael@0: // NOTE: the start of value field inside the data field is always on a 32 bit boundary: michael@0: // michael@0: // +-----------+ michael@0: // | status | sizeof(int) michael@0: // +-----------+ michael@0: // | psize | sizeof(int) michael@0: // +-----------+ michael@0: // | vsize | sizeof(int) michael@0: // +-----------+ michael@0: // | | | | michael@0: // ~ parameter ~ > psize | michael@0: // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int) michael@0: // +-----------+ | michael@0: // | padding | | michael@0: // +-----------+ michael@0: // | | | michael@0: // ~ value ~ > vsize michael@0: // | | | michael@0: // +-----------+ michael@0: michael@0: typedef struct effect_param_s { michael@0: int32_t status; // Transaction status (unused for command, used for reply) michael@0: uint32_t psize; // Parameter size michael@0: uint32_t vsize; // Value size michael@0: char data[]; // Start of Parameter + Value data michael@0: } effect_param_t; michael@0: michael@0: michael@0: ///////////////////////////////////////////////// michael@0: // Effect library interface michael@0: ///////////////////////////////////////////////// michael@0: michael@0: // An effect library is required to implement and expose the following functions michael@0: // to enable effect enumeration and instantiation. The name of these functions must be as michael@0: // specified here as the effect framework will get the function address with dlsym(): michael@0: // michael@0: // - effect_QueryNumberEffects_t EffectQueryNumberEffects; michael@0: // - effect_QueryEffect_t EffectQueryEffect; michael@0: // - effect_CreateEffect_t EffectCreate; michael@0: // - effect_ReleaseEffect_t EffectRelease; michael@0: michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: EffectQueryNumberEffects michael@0: // michael@0: // Description: Returns the number of different effects exposed by the michael@0: // library. Each effect must have a unique effect uuid (see michael@0: // effect_descriptor_t). This function together with EffectQueryEffect() michael@0: // is used to enumerate all effects present in the library. michael@0: // michael@0: // Input/Output: michael@0: // pNumEffects: address where the number of effects should be returned. michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation. michael@0: // -ENODEV library failed to initialize michael@0: // -EINVAL invalid pNumEffects michael@0: // *pNumEffects: updated with number of effects in library michael@0: // michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_QueryNumberEffects_t)(uint32_t *pNumEffects); michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: EffectQueryEffect michael@0: // michael@0: // Description: Returns the descriptor of the effect engine which index is michael@0: // given as first argument. michael@0: // See effect_descriptor_t for details on effect descriptors. michael@0: // This function together with EffectQueryNumberEffects() is used to enumerate all michael@0: // effects present in the library. The enumeration sequence is: michael@0: // EffectQueryNumberEffects(&num_effects); michael@0: // for (i = 0; i < num_effects; i++) michael@0: // EffectQueryEffect(i,...); michael@0: // michael@0: // Input/Output: michael@0: // index: index of the effect michael@0: // pDescriptor: address where to return the effect descriptor. michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation. michael@0: // -ENODEV library failed to initialize michael@0: // -EINVAL invalid pDescriptor or index michael@0: // -ENOSYS effect list has changed since last execution of michael@0: // EffectQueryNumberEffects() michael@0: // -ENOENT no more effect available michael@0: // *pDescriptor: updated with the effect descriptor. michael@0: // michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_QueryEffect_t)(uint32_t index, michael@0: effect_descriptor_t *pDescriptor); michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: EffectCreate michael@0: // michael@0: // Description: Creates an effect engine of the specified type and returns an michael@0: // effect control interface on this engine. The function will allocate the michael@0: // resources for an instance of the requested effect engine and return michael@0: // a handle on the effect control interface. michael@0: // michael@0: // Input: michael@0: // uuid: pointer to the effect uuid. michael@0: // sessionId: audio session to which this effect instance will be attached. All effects michael@0: // created with the same session ID are connected in series and process the same signal michael@0: // stream. Knowing that two effects are part of the same effect chain can help the michael@0: // library implement some kind of optimizations. michael@0: // ioId: identifies the output or input stream this effect is directed to at audio HAL. michael@0: // For future use especially with tunneled HW accelerated effects michael@0: // michael@0: // Input/Output: michael@0: // pInterface: address where to return the effect interface. michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation. michael@0: // -ENODEV library failed to initialize michael@0: // -EINVAL invalid pEffectUuid or pInterface michael@0: // -ENOENT no effect with this uuid found michael@0: // *pInterface: updated with the effect interface handle. michael@0: // michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_CreateEffect_t)(effect_uuid_t *uuid, michael@0: int32_t sessionId, michael@0: int32_t ioId, michael@0: effect_interface_t *pInterface); michael@0: michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: // michael@0: // Function: EffectRelease michael@0: // michael@0: // Description: Releases the effect engine whose handle is given as argument. michael@0: // All resources allocated to this particular instance of the effect are michael@0: // released. michael@0: // michael@0: // Input: michael@0: // interface: handle on the effect interface to be released. michael@0: // michael@0: // Output: michael@0: // returned value: 0 successful operation. michael@0: // -ENODEV library failed to initialize michael@0: // -EINVAL invalid interface handle michael@0: // michael@0: //////////////////////////////////////////////////////////////////////////////// michael@0: typedef int32_t (*effect_ReleaseEffect_t)(effect_interface_t interface); michael@0: michael@0: michael@0: #if __cplusplus michael@0: } // extern "C" michael@0: #endif michael@0: michael@0: michael@0: #endif /*ANDROID_EFFECTAPI_H_*/