version 2.8
gaudio_driver_play.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gaudio/gaudio_driver_play.h
10  * @brief GAUDIO - Audio play driver header file.
11  *
12  * @defgroup GAUDIO_Driver_Playback Driver Playback
13  * @ingroup GAUDIO
14  *
15  * @brief Playback driver interface for the GAUDIO module.
16  *
17  * @{
18  */
19 
20 #ifndef _GAUDIO_PLAY_LLD_H
21 #define _GAUDIO_PLAY_LLD_H
22 
23 #include "../../gfx.h"
24 
25 #if (GFX_USE_GAUDIO && GAUDIO_NEED_PLAY) || defined(__DOXYGEN__)
26 
27 /*===========================================================================*/
28 /* Type definitions */
29 /*===========================================================================*/
30 
31 /*===========================================================================*/
32 /* External declarations. */
33 /*===========================================================================*/
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 /**
40  * @brief Get a block of audio data to play
41  * @return A pointer to the GAaudioData structure or NULL if none is currently available
42  *
43  * @note Defined in the high level GAUDIO code for use by the GAUDIO play drivers.
44  *
45  * @iclass
46  * @notapi
47  */
49 
50 /**
51  * @brief Release a block of audio data to the free list
52  *
53  * @param[in] paud The GDataBuffer block to be released.
54  *
55  * @note Defined in the high level GAUDIO code for use by the GAUDIO play drivers.
56  *
57  * @iclass
58  * @notapi
59  */
61 
62 /**
63  * @brief Signal that all playing has now stopped
64  *
65  * @note Defined in the high level GAUDIO code for use by the GAUDIO play drivers.
66  *
67  * @iclass
68  * @notapi
69  */
70 void gaudioPlayDoneI(void);
71 
72 /**
73  * @brief Initialise the play driver
74  * @return TRUE if the channel, frequency and format are valid.
75  *
76  * @param[in] channel The channel to use (see the driver for the available channels provided)
77  * @param[in] frequency The sample frequency to use
78  * @param[in] format The sample format
79  *
80  * @note The driver will always have been stopped and de-init before this is called.
81  *
82  * @api
83  */
84 bool_t gaudio_play_lld_init(uint16_t channel, uint32_t frequency, ArrayDataFormat format);
85 
86 /**
87  * @brief Start the audio output playing
88  *
89  * @note This may be called at any stage including while the driver
90  * is already playing. The driver should check for data blocks
91  * to play using @p gaudioPlayGetDataBlockI().
92  *
93  * @api
94  */
95 void gaudio_play_lld_start(void);
96 
97 /**
98  * @brief Stop the audio output playing.
99  *
100  * @note Some drivers may only stop playing at a data block boundary.
101  * @note It is possible but unlikely for it to be called when playing has already stopped.
102  * @note It should not return until all active buffers (currently in use by the driver)
103  * have been returned to the free-list and @p gaudioPlayDoneI() has been called.
104  *
105  * @api
106  */
107 void gaudio_play_lld_stop(void);
108 
109 /**
110  * @brief Set the output volume.
111  * @return TRUE if successful.
112  *
113  * @param[in] vol 0->255 (0 = muted)
114  *
115  * @note Some drivers may not support this. They will return FALSE.
116  * @note For stereo devices, both channels are set to the same volume.
117  *
118  * @api
119  */
120 bool_t gaudio_play_lld_set_volume(uint8_t vol);
121 
122 #ifdef __cplusplus
123 }
124 #endif
125 
126 #endif /* GFX_USE_GAUDIO && GAUDIO_NEED_PLAY */
127 
128 #endif /* _GAUDIO_PLAY_LLD_H */
129 /** @} */
A Data Buffer Queue.
Definition: gqueue.h:78
void gaudio_play_lld_start(void)
Start the audio output playing.
void gaudioPlayReleaseDataBlockI(GDataBuffer *paud)
Release a block of audio data to the free list.
void gaudioPlayDoneI(void)
Signal that all playing has now stopped.
bool_t gaudio_play_lld_set_volume(uint8_t vol)
Set the output volume.
bool_t gaudio_play_lld_init(uint16_t channel, uint32_t frequency, ArrayDataFormat format)
Initialise the play driver.
GDataBuffer * gaudioPlayGetDataBlockI(void)
Get a block of audio data to play.
enum ArrayDataFormat_e ArrayDataFormat
Sample data formats.
void gaudio_play_lld_stop(void)
Stop the audio output playing.