blob: 75cda243789c355c6e77371781d43668bb8a754e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
/*
* This file is subject to the terms of the GFX License. If a copy of
* the license was not distributed with this file, you can obtain one at:
*
* http://ugfx.org/license.html
*/
/**
* @file src/gaudout/sys_defs.h
*
* @addtogroup GAUDOUT
*
* @brief Module to output audio data (under development)
*
* @{
*/
#ifndef _GAUDOUT_H
#define _GAUDOUT_H
#include "gfx.h"
#if GFX_USE_GAUDOUT || defined(__DOXYGEN__)
/* Include the driver defines */
#include "gaudout_lld_config.h"
/*===========================================================================*/
/* Type definitions */
/*===========================================================================*/
/**
* @brief Contains Audio Data Samples
* @note This structure is followed immediately by the sample data itself.
* When allocating the buffers for the sample data put this structure
* at the beginning of the buffer.
*/
typedef struct GAudioData {
gfxQueueASyncItem next; // @< Used for queuing the buffers
size_t size; // @< The size of the buffer area following this structure (in bytes)
size_t len; // @< The length of the data in the buffer area (in bytes)
} GAudioData;
// Event types for GAUDOUT
#define GEVENT_AUDIO_OUT (GEVENT_GAUDOUT_FIRST+0)
/**
* @brief The Audio output event structure.
* @{
*/
typedef struct GEventAudioOut_t {
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
/**
* @brief The type of this event (GEVENT_AUDIO_OUT)
*/
GEventType type;
#endif
/**
* @brief The event flags
*/
uint16_t flags;
/**
* @brief The event flag values.
* @{
*/
#define GAUDOUT_LOSTEVENT 0x0001 /**< @brief The last GEVENT_AUDIO_OUT event was lost */
#define GAUDOUT_PLAYING 0x0002 /**< @brief The audio out system is currently playing */
#define GAUDOUT_FREEBLOCK 0x0004 /**< @brief An audio buffer has been freed */
/** @} */
} GEventAudioOut;
/** @} */
/*===========================================================================*/
/* External declarations. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Allocate some audio buffers and put them on the free list
* @return TRUE is it succeeded. FALSE on allocation failure.
*
* @param[in] num The number of buffers to allocate
* @param[in] size The size (in bytes) of each buffer
*
* @api
*/
bool_t gaudioAllocBuffers(unsigned num, size_t size);
/**
* @brief Get an audio buffer from the free list
* @return A GAudioData pointer or NULL if the timeout is exceeded
*
* @params[in] ms The maximum amount of time in milliseconds to wait for a buffer if one is not available.
*
* @api
*/
GAudioData *gaudioGetBuffer(delaytime_t ms);
/**
* @brief Release a buffer back to the free list
*
* @param[in] paud The buffer to put (back) on the free-list.
*
* @note This call should be used to return any buffers that were taken from
* the free-list once they have been finished with. It can also be used
* to put new buffers onto the free-list. Just make sure the "size" field
* of the GAudioData structure has been filled in first.
*
* @api
*/
void gaudioReleaseBuffer(GAudioData *paud);
/**
* @brief Set the audio device to play on the specified channel and with the specified
* sample frequency.
* @return TRUE is successful, FALSE if the driver doesn't accept those parameters.
*
* @param[in] channel The audio output channel to use.
* @param[in] frequency The audio sample rate in samples per second
* @param[in] format The audio sample format
*
* @note Some channels are mono, and some are stereo. See your driver config file
* to determine which channels to use and whether they are stereo or not.
* @note Only one channel can be playing at a time. Calling this will stop any
* currently playing channel.
*
* @api
*/
bool_t gaudioPlayInit(uint16_t channel, uint32_t frequency, ArrayDataFormat format);
/**
* @brief Play the specified sample data.
* @details The sample data is output to the audio channel. On completion the buffer is returned to the free-list.
* @pre @p gaudioPlayInit must have been called first to set the channel and sample frequency.
*
* @param[in] paud The audio sample buffer to play. It can be NULL (used to restart paused audio)
*
* @note Calling this will cancel any pause.
* @note Before calling this function the len field of the GAudioData structure must be
* specified (in bytes).
* @note For stereo channels the sample data is interleaved in the buffer.
* @note This call returns before the data has completed playing. Subject to available buffers (which
* can be obtained from the free-list), any number of buffers may be played. They will be queued
* for playing in the order they are supplied to this routine and played when previous buffers are
* complete. In this way continuous playing can be obtained without audio gaps.
*
* @api
*/
void gaudioPlay(GAudioData *paud);
/**
* @brief Pause any currently playing sounds.
*
* @note If nothing is currently playing this routine does nothing. To restart playing call @p gaudioPlay()
* with or without a new sample buffer.
* @note Some drivers will not respond until a buffer boundary.
*
* @api
*/
void gaudioPlayPause(void);
/**
* @brief Stop any currently playing sounds.
*
* @note This stops any playing sounds and returns any currently queued buffers back to the free-list.
* @note Some drivers will not respond until a buffer boundary.
*
* @api
*/
void gaudioPlayStop(void);
/**
* @brief Set the output volume.
* @return TRUE if successful.
*
* @param[in] 0->255 (0 = muted)
*
* @note Some drivers may not support this. They will return FALSE.
* @note For stereo devices, both channels are set to the same volume.
*
* @api
*/
bool_t gaudioPlaySetVolume(uint8_t vol);
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
/**
* @brief Turn on sending results to the GEVENT sub-system.
* @details Returns a GSourceHandle to listen for GEVENT_AUDIO_OUT events.
*
* @note The audio output will not use the GEVENT system unless this is
* called first. This saves processing time if the application does
* not want to use the GEVENT sub-system for audio output.
* Once turned on it can only be turned off by calling @p gaudioPlayInit() again.
* @note The audio output is capable of signalling via this method and other methods
* at the same time.
*
* @return The GSourceHandle
*
* @api
*/
GSourceHandle gaudioPlayGetSource(void);
#endif
#ifdef __cplusplus
}
#endif
#endif /* GFX_USE_GAUDOUT */
#endif /* _GAUDOUT_H */
/** @} */
|
