diff --git a/src/lib/ecore_audio/Ecore_Audio.h b/src/lib/ecore_audio/Ecore_Audio.h index c40514091c..212a4f398b 100644 --- a/src/lib/ecore_audio/Ecore_Audio.h +++ b/src/lib/ecore_audio/Ecore_Audio.h @@ -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 +/** + * @} + */ + #endif diff --git a/src/lib/ecore_audio/ecore_audio_obj.h b/src/lib/ecore_audio/ecore_audio_obj.h index 625aad5ed6..fc8d8ebb2f 100644 --- a/src/lib/ecore_audio/ecore_audio_obj.h +++ b/src/lib/ecore_audio/ecore_audio_obj.h @@ -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 diff --git a/src/lib/ecore_audio/ecore_audio_private.h b/src/lib/ecore_audio/ecore_audio_private.h index f634beabe2..35afa85f4c 100644 --- a/src/lib/ecore_audio/ecore_audio_private.h +++ b/src/lib/ecore_audio/ecore_audio_private.h @@ -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 */