kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

ecore_audio: Update documentation and document ecore_audio_obj 

Remove old unused function declarations

Signed-off-by: Daniel Willmann <d.willmann@samsung.com>
This commit is contained in:
Daniel Willmann 2013-05-01 16:26:49 +01:00
parent 5dde3b3bfd
commit c249dc8cee
3 changed files with 197 additions and 485 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

562
src/lib/ecore_audio/Ecore_Audio.h
View File

@ -31,7 +31,11 @@ extern "C"
/**
* @defgroup Ecore_Audio_Group Ecore_Audio - Convenience audio API
* @ingroup Ecore
*
@section Classes
Ecore_Audio provides the following Eo classes:
@li @ref ecore_audio_obj
* @since 1.8
*
* @{
@ -48,18 +52,27 @@ enum _Ecore_Audio_Type {
ECORE_AUDIO_MODULE_LAST, /**< Sentinel */
};
enum _Ecore_Audio_Format {
ECORE_AUDIO_FORMAT_AUTO,
ECORE_AUDIO_FORMAT_RAW,
ECORE_AUDIO_FORMAT_WAV,
ECORE_AUDIO_FORMAT_OGG,
ECORE_AUDIO_FORMAT_FLAC,
ECORE_AUDIO_FORMAT_MP3,
ECORE_AUDIO_FORMAT_LAST
};
/**
* @since 1.8
*/
typedef enum _Ecore_Audio_Type Ecore_Audio_Type;
/**
* @since 1.8
*/
enum _Ecore_Audio_Format {
ECORE_AUDIO_FORMAT_AUTO, /**< Automatically detect the format (for inputs) */
ECORE_AUDIO_FORMAT_RAW, /**< RAW samples (float) */
ECORE_AUDIO_FORMAT_WAV, /**< WAV format */
ECORE_AUDIO_FORMAT_OGG, /**< OGG */
ECORE_AUDIO_FORMAT_FLAC, /**< FLAC, the Free Lossless Audio Codec */
ECORE_AUDIO_FORMAT_MP3, /**< MP3 (not supported) */
ECORE_AUDIO_FORMAT_LAST /**< Sentinel value, do not use */
};
/*
* @since 1.8
*/
typedef enum _Ecore_Audio_Format Ecore_Audio_Format;
/**< The format of the audio data */
@ -72,18 +85,88 @@ typedef struct _Ecore_Audio_Module Ecore_Audio_Module;
*/
typedef struct _Ecore_Audio_Object Ecore_Audio_Object; /**< The audio object */
typedef int (*Ecore_Audio_Read_Callback)(void *user_data, void *data, int len);
/*
* @since 1.8
*/
struct _Ecore_Audio_Vio {
/**
* @brief Get the length of the file
*
* @param data User data from the ecore_audio_obj_set_vio call
* @param eo_obj The Ecore_Audio object this operates on
*
* @return The length of the virtual file in bytes
*
* @since 1.8
*/
int (*get_length)(void *data, Eo *eo_obj);
/**
* @brief Seek to a position within the file
*
* @param data User data from the ecore_audio_obj_set_vio call
* @param eo_obj The Ecore_Audio object this operates on
* @param offset The number of bytes to move (can be negative)
* @param whence Accepts the same values as fseek(), which are:
* SEEK_SET: offset is absolute
* SEEK_CUR: offset is relative to the current position
* SEEK_END: offset is relative to the end
*
* @return The resulting position from the start of the file (in bytes)
* or -1 if an error occured (i.e. out of bounds)
*
* @since 1.8
*/
int (*seek)(void *data, Eo *eo_obj, int offset, int whence);
/**
* @brief Get the current position within the file
*
* @param data User data from the ecore_audio_obj_set_vio call
* @param eo_obj The Ecore_Audio object this operates on
*
* @return The resulting position from the start of the file (in bytes)
*
* This is equivalent to calling seek() with offset 0 and whence SEEK_CUR.
*
* @since 1.8
*/
int (*tell)(void *data, Eo *eo_obj);
/**
* @brief Read some data from the file
*
* @param data User data from the ecore_audio_obj_set_vio call
* @param eo_obj The Ecore_Audio object this operates on
* @param[out] buffer the buffer to write the data to
* @param length The number of bytes to read
*
* @return The number of bytes read from the file. May be less than length
*
* @since 1.8
*/
int (*read)(void *data, Eo *eo_obj, void *buffer, int length);
/**
* @brief Write some data to the file
*
* @param data User data from the ecore_audio_obj_set_vio call
* @param eo_obj The Ecore_Audio object this operates on
* @param buffer Write data from here to the file
* @param length The number of bytes to write
*
* @return The number of bytes written to the file. May be less than length
*
* @since 1.8
*/
int (*write)(void *data, Eo *eo_obj, const void *buffer, int length);
};
typedef struct _Ecore_Audio_Vio Ecore_Audio_Vio; /**< Functions to implement IO virtually */
/**
* @brief Holds the callback functions to implement virtual file IO
* @since 1.8
*/
typedef struct _Ecore_Audio_Vio Ecore_Audio_Vio;
/* Audio operations */
@ -118,451 +201,6 @@ EAPI int ecore_audio_init(void);
EAPI int ecore_audio_shutdown(void);
/* Output operations*/
/**
* @brief Create a new Ecore_Audio_Output instance
*
* @param name the name of the output to create
* @return a new instance or NULL on error
*
* @since 1.8
*/
EAPI Ecore_Audio_Object *ecore_audio_output_add(Ecore_Audio_Type type);
/**
* @brief Set the name of an output
*
* @param output The output
* @param name The name
*
* @since 1.8
*/
EAPI void ecore_audio_output_name_set(Ecore_Audio_Object *output, const char *name);
/**
* @brief Get the name of an output
*
* @param output the output
*
* @return the name of the output
*
* @since 1.8
*/
EAPI const char *ecore_audio_output_name_get(Ecore_Audio_Object *output);
/**
* @brief Free an @ref Ecore_Audio_Output instance
*
* @param out the output
*
* @since 1.8
*/
EAPI void ecore_audio_output_del(Ecore_Audio_Object *output);
/**
* @brief Set the user data pointer
*
* @param output The output
* @param data The pointer to set
*
* @since 1.8
*/
EAPI void ecore_audio_output_data_set(Ecore_Audio_Object *output, void *data);
/**
* @brief Get the user data pointer
*
* @param output The output
*
* @return The pointer to the user data
*
* @since 1.8
*/
EAPI void *ecore_audio_output_data_get(Ecore_Audio_Object *output);
/**
* @brief Set the volume of the output
*
* @param out the output
* @param volume the volume
*
* @since 1.8
*/
EAPI void ecore_audio_output_volume_set(Ecore_Audio_Object *output, double volume);
/**
* @brief Get the volume of the output
*
* @param out the output
*
* @return the volume
*
* @since 1.8
*/
EAPI double ecore_audio_output_volume_get(Ecore_Audio_Object *output);
/**
* @brief Set the paused state of an output
*
* @param out the output
* @param paused the paused state
*
* @since 1.8
*/
EAPI void ecore_audio_output_paused_set(Ecore_Audio_Object *output, Eina_Bool paused);
/**
* @brief Get the paused state of an output
*
* @param out the output
*
* @return the paused state
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_output_paused_get(Ecore_Audio_Object *output);
/**
* @brief Add an input to an output.
*
* @param out the output
* @param in the input
*
* @return True if connecting was successful, False otherwise
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_output_input_add(Ecore_Audio_Object *output, Ecore_Audio_Object *input);
/**
* @brief Disconnect an input from an output. This will stop playback of the
* input.
*
* @param out the output
* @param in the input
*
* @return True if disconnecting was successful, False otherwise
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_output_input_del(Ecore_Audio_Object *output, Ecore_Audio_Object *input);
/**
* @brief Get the inputs connected to an output.
*
* @param out the output
*
* @return A list of Ecore_Audio_Input that are connected to the output
*
* @since 1.8
*/
EAPI Eina_List *ecore_audio_output_inputs_get(Ecore_Audio_Object *output);
/**
* @brief Set up an input to play after another input.
*
* @param out the output
* @param after the input relative to which the other input will be chained
* @param in the input to chain
*
* @return True if chaining was successful, False otherwise
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_output_input_chain_after(Ecore_Audio_Object *output, Ecore_Audio_Object *input, Ecore_Audio_Object *after);
/* Input operations*/
/**
* @brief Create a new Ecore_Audio_Input instance
*
* @param name the name of the input to create
* @return a new instance or NULL on error
*
* @since 1.8
*/
EAPI Ecore_Audio_Object *ecore_audio_input_add(Ecore_Audio_Type type);
/**
* @brief Get the name of an input
*
* @param input the input
*
* @return the name of the input
*
* @since 1.8
*/
EAPI const char *ecore_audio_input_name_get(Ecore_Audio_Object *input);
/**
* @brief Set the name of an input
*
* @param input the input
* @param name The name to set
*
* @since 1.8
*/
EAPI void ecore_audio_input_name_set(Ecore_Audio_Object *input, const char *name);
/**
* @brief Free an @ref Ecore_Audio_Input instance
*
* @param in the input
*
* @since 1.8
*/
EAPI void ecore_audio_input_del(Ecore_Audio_Object *input);
/**
* @brief Set the user data pointer
*
* @param input The input
* @param data The pointer to set
*
* @since 1.8
*/
EAPI void ecore_audio_input_data_set(Ecore_Audio_Object *input, void *data);
/**
* @brief Get the user data pointer
*
* @param input The input
*
* @return The pointer to the user data
*
* @since 1.8
*/
EAPI void *ecore_audio_input_data_get(Ecore_Audio_Object *input);
/**
* @brief Get the sample rate of the input
*
* @param input The input
*
* @return The samplerate in Hz
*
* @since 1.8
*/
EAPI int ecore_audio_input_samplerate_get(Ecore_Audio_Object *input);
/**
* @brief Set the sample rate of the input
*
* @param input The input
* @param samplerate The sample rate in Hz
*
* @since 1.8
*/
EAPI void ecore_audio_input_samplerate_set(Ecore_Audio_Object *input, int samplerate);
/**
* @brief Get the speed the input is played back at
*
* @param input The input
*
* @return The speed
*
* @since 1.8
*/
EAPI double ecore_audio_input_speed_get(Ecore_Audio_Object *input);
/**
* @brief Set the speed the input is played back at
*
* @param input The input
* @param samplerate The speed (1.0 is normal speed)
*
* @since 1.8
*/
EAPI void ecore_audio_input_speed_set(Ecore_Audio_Object *input, double speed);
/**
* @brief Get the channels of the input
*
* @param input The input
*
* @return The number of channels
*
* @since 1.8
*/
EAPI int ecore_audio_input_channels_get(Ecore_Audio_Object *input);
/**
* @brief Set the amount of channels in the input
*
* @param input The input
* @param channels The number of channels to set
*
* @since 1.8
*/
EAPI void ecore_audio_input_channels_set(Ecore_Audio_Object *input, int channels);
/**
* @brief Seek within an input stream
*
* @param in the input
* @offset the offset in seconds
* @mode seek mode (SEEK_SET, SEEK_END, or SEEK_CUR)
* @return the current offset
*
* @since 1.8
*/
EAPI double ecore_audio_input_seek(Ecore_Audio_Object *input, double offset, int mode);
/**
* @brief Read data from an input stream
*
* @param in the input
* @param data the buffer to write the audio data into
* @param len the size of the buffer
*
* @return the number of bytes that were read
*
* @since 1.8
*/
EAPI int ecore_audio_input_read(Ecore_Audio_Object *input, void *data, int len);
/**
* @brief Get the paused state of an input
*
* @param in the input
* @return EINA_TRUE if the input is paused, EINA_FALSE otherwise
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_input_paused_get(Ecore_Audio_Object *input);
/**
* @brief Set the paused state of an input
*
* @param in the input
* @param paused the paused state to set
*
* @since 1.8
*
* If paused is EINA_TRUE if the input is paused, if it is EINA_FALSE the
* input plays normally.
*/
EAPI void ecore_audio_input_paused_set(Ecore_Audio_Object *input, Eina_Bool paused);
/**
* @brief Set the volume of the input
*
* @param in the input
* @param volume the volume
*
* @since 1.8
*/
EAPI void ecore_audio_input_volume_set(Ecore_Audio_Object *input, double volume);
/**
* @brief Get the volume of the input
*
* @param in the input
*
* @return the volume
*
* @since 1.8
*/
EAPI double ecore_audio_input_volume_get(Ecore_Audio_Object *input);
/**
* @brief Set whether the input loops
*
* @param in the input
* @param looped if the input should loop
*
* @since 1.8
*/
EAPI void ecore_audio_input_looped_set(Ecore_Audio_Object *input, Eina_Bool looped);
/**
* @brief Get whether the input loops
*
* @param in the input
*
* @return if the input loops
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_input_looped_get(Ecore_Audio_Object *input);
/**
* @brief Get the length of the input in seconds
*
* @param in the input
*
* @return the length in seconds
*
* @since 1.8
*/
EAPI double ecore_audio_input_length_get(Ecore_Audio_Object *input);
/**
* @brief Set whether the input is preloaded
*
* @param in the input
* @param preloaded if the input is preloaded
*
* @since 1.8
*/
EAPI void ecore_audio_input_preloaded_set(Ecore_Audio_Object *input, Eina_Bool preloaded);
/**
* @brief Get whether the input is preloaded
*
* @param in the input
*
* @return EINA_TRUE if the input is preloaded, otherwise EINA_FALSE
*
* @since 1.8
*/
EAPI Eina_Bool ecore_audio_input_preloaded_get(Ecore_Audio_Object *input);
/**
* @brief Get the outputs this input is connected to
*
* @param in the input
*
* @return A list of outputs
*
* @since 1.8
*/
EAPI Ecore_Audio_Object *ecore_audio_input_output_get(Ecore_Audio_Object *input);
/**
* @brief Get the remaining time of the input
*
* @param in the input
*
* @return The remaining time in seconds
*
* @since 1.8
*/
EAPI double ecore_audio_input_remaining_get(Ecore_Audio_Object *input);
/* libsndfile */
EAPI void ecore_audio_input_sndfile_filename_set(Ecore_Audio_Object *input, const char *filename);
EAPI void ecore_audio_input_sndfile_format_set(Ecore_Audio_Object *input, int format);
EAPI void ecore_audio_input_sndfile_vio_set(Ecore_Audio_Object *input, Ecore_Audio_Vio *vio);
EAPI void ecore_audio_output_sndfile_filename_set(Ecore_Audio_Object *output, const char *filename);
EAPI void ecore_audio_output_sndfile_format_set(Ecore_Audio_Object *output, int format);
EAPI void ecore_audio_output_sndfile_vio_set(Ecore_Audio_Object *output, Ecore_Audio_Vio *vio);
/* tone */
EAPI void ecore_audio_input_tone_frequency_set(Ecore_Audio_Object *input, int frequency);
EAPI void ecore_audio_input_tone_duration_set(Ecore_Audio_Object *input, double duration);
EAPI void ecore_audio_input_callback_setup(Ecore_Audio_Object *input, Ecore_Audio_Read_Callback read_cb, void *data);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
@ -578,4 +216,8 @@ EAPI void ecore_audio_input_callback_setup(Ecore_Audio_Object *in
#include <ecore_audio_obj_out_pulse.h>
/**
* @}
*/
#endif

110
src/lib/ecore_audio/ecore_audio_obj.h
View File

@ -20,7 +20,7 @@
/**
* @file ecore_audio_obj.h
* @brief Audio Object
* @brief Base Ecore_Audio object
*/
#ifdef __cplusplus
@ -29,12 +29,18 @@ extern "C"
#endif
/**
* @addtogroup Ecore_Audio_Group
* @defgroup ecore_audio_obj - Base Ecore_Audio object
* @ingroup Ecore_Audio_Group
* @{
*/
#define ECORE_AUDIO_OBJ_CLASS ecore_audio_obj_class_get()
#define ECORE_AUDIO_OBJ_CLASS ecore_audio_obj_class_get() /**< Ecore_Audio object class */
/**
* @brief Get the Eo class ID
*
* @return The Eo class ID
*/
const Eo_Class *ecore_audio_obj_class_get() EINA_CONST;
extern EAPI Eo_Op ECORE_AUDIO_OBJ_BASE_ID;
@ -57,48 +63,122 @@ enum Ecore_Audio_Obj_Sub_Ids
#define ECORE_AUDIO_OBJ_ID(sub_id) (ECORE_AUDIO_OBJ_BASE_ID + EO_TYPECHECK(enum Ecore_Audio_Obj_Sub_Ids, sub_id))
/*
* @def ecore_audio_obj_name_set
* @since 1.8
/**
* @brief Set the name of the object
*
* Sets the name of the object
* @since 1.8
*
* @param[in] name
*/
#define ecore_audio_obj_name_set(name) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_NAME_SET), EO_TYPECHECK(const char *, name)
/*
* @def ecore_audio_obj_name_get
/**
* @brief Get the name of the object
*
* @since 1.8
*
* Gets the name of the object
*
* @param[out] name
* @param[out] ret
*/
#define ecore_audio_obj_name_get(name) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_NAME_GET), EO_TYPECHECK(const char **, name)
#define ecore_audio_obj_name_get(ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_NAME_GET), EO_TYPECHECK(const char **, ret)
/**
* @brief Set the paused state of the object
*
* @since 1.8
*
* @param[in] paused EINA_TRUE to pause the object, EINA_FALSE to resume
*/
#define ecore_audio_obj_paused_set(paused) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_PAUSED_SET), EO_TYPECHECK(Eina_Bool, paused)
/**
* @brief Get the paused state of the object
*
* @since 1.8
*
* @param[out] ret EINA_TRUE if object is paused, EINA_FALSE if not
*/
#define ecore_audio_obj_paused_get(ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_PAUSED_GET), EO_TYPECHECK(Eina_Bool *, ret)
/**
* @brief Set the volume of the object
*
* @since 1.8
*
* @param[in] volume The volume, 1.0 is the default, can be > 1.0
*/
#define ecore_audio_obj_volume_set(volume) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_VOLUME_SET), EO_TYPECHECK(double, volume)
/**
* @brief Get the volume of the object
*
* @since 1.8
*
* @param[out] ret The volume
*/
#define ecore_audio_obj_volume_get(ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_VOLUME_GET), EO_TYPECHECK(double *, ret)
/**
* @brief Set the source of an object
*
* @since 1.8
*
* What sources are supported depends on the actual object. For example,
* the libsndfile class accepts WAV, OGG, FLAC files as source.
*
* @param[in] source The source to set to (i.e. file, URL, device)
* @param[out] ret EINA_TRUE if the source was set correctly (i.e. the file was opened), EINA_FALSE otherwise
*/
#define ecore_audio_obj_source_set(source, ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_SOURCE_SET), EO_TYPECHECK(const char *, source), EO_TYPECHECK(Eina_Bool *, ret)
#define ecore_audio_obj_source_get(source) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_SOURCE_GET), EO_TYPECHECK(const char **, source)
/**
* @brief Get the source of an object
*
* @since 1.8
*
* @param[out] ret The currently set source
*/
#define ecore_audio_obj_source_get(ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_SOURCE_GET), EO_TYPECHECK(const char **, ret)
/**
* @brief Set the format of an object
*
* @since 1.8
*
* What formats are supported depends on the actual object. Default is
* ECORE_AUDIO_FORMAT_AUTO
*
* @param[in] format The format to set, of type Ecore_Audio_Format
* @param[out] ret EINA_TRUE if the format was supported, EINA_FALSE otherwise
*/
#define ecore_audio_obj_format_set(format, ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_FORMAT_SET), EO_TYPECHECK(Ecore_Audio_Format, format), EO_TYPECHECK(Eina_Bool *, ret)
/**
* @brief Get the format of an object
*
* @since 1.8
*
* After setting the source if the format was ECORE_AUDIO_FORMAT_AUTO this
* function will now return the actual format.
*
* @param[out] ret The format of the object
*/
#define ecore_audio_obj_format_get(ret) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_FORMAT_GET), EO_TYPECHECK(Ecore_Audio_Format *, ret)
/**
* @brief Set the virtual IO functions
*
* @since 1.8
*
* @param[in] vio The @ref Ecore_Audio_Vio struct with the function callbacks
* @param[in] data User data to pass to the VIO functions
* @param[in] free_func This function takes care to clean up @ref data when
* the VIO is destroyed. NULL means do nothing.
*/
#define ecore_audio_obj_vio_set(vio, data, free_func) ECORE_AUDIO_OBJ_ID(ECORE_AUDIO_OBJ_SUB_ID_VIO_SET), EO_TYPECHECK(Ecore_Audio_Vio *, vio), EO_TYPECHECK(void *, data), EO_TYPECHECK(eo_base_data_free_func, free_func)
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
src/lib/ecore_audio/ecore_audio_private.h
View File

@ -142,11 +142,6 @@ struct _Ecore_Audio_Input
Eina_Bool ended;
};
struct _Ecore_Audio_Callback {
Ecore_Audio_Read_Callback read_cb;
void *data;
};
extern Eina_List *ecore_audio_modules;
#ifdef HAVE_ALSA
@ -170,11 +165,6 @@ void ecore_audio_pulse_shutdown(void);
#ifdef HAVE_SNDFILE
/* ecore_audio_sndfile */
struct _Ecore_Audio_Sndfile_Private
{
SF_VIRTUAL_IO vio_wrapper;
};
Ecore_Audio_Module *ecore_audio_sndfile_init(void);
void ecore_audio_sndfile_shutdown(void);
#endif /* HAVE_SNDFILE */