GCC Code Coverage Report

Line	Branch	Exec	Source
1			/* GATE PROJECT LICENSE:
2			+----------------------------------------------------------------------------+
3			| Copyright(c) 2018-2025, Stefan Meislinger <sm@opengate.at> |
4			| All rights reserved. |
5			| |
6			| Redistribution and use in source and binary forms, with or without |
7			| modification, are permitted provided that the following conditions are met:|
8			| |
9			| 1. Redistributions of source code must retain the above copyright notice, |
10			| this list of conditions and the following disclaimer. |
11			| 2. Redistributions in binary form must reproduce the above copyright |
12			| notice, this list of conditions and the following disclaimer in the |
13			| documentation and/or other materials provided with the distribution. |
14			| |
15			| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"|
16			| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
17			| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
18			| ARE DISCLAIMED.IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
19			| LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
20			| CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
21			| SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
22			| INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
23			| CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
24			| ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF |
25			| THE POSSIBILITY OF SUCH DAMAGE. |
26			+----------------------------------------------------------------------------+
27			*/
28
29			/** @file
30			* @brief Audio devices and audio sample data formats
31			* @ingroup gateio
32			*/
33
34			#ifndef GATE_IO_AUDIOSOURCES_H_INCLUDED
35			#define GATE_IO_AUDIOSOURCES_H_INCLUDED
36
37			#include "gate/io/gate_io_api.h"
38			#include "gate/gatetypes.h"
39			#include "gate/memalloc.h"
40			#include "gate/strings.h"
41			#include "gate/streams.h"
42			#include "gate/times.h"
43			#include "gate/objects.h"
44			#include "gate/arrays.h"
45			#include "gate/delegates.h"
46			#include "gate/comparers.h"
47
48			#if defined(__cplusplus)
49			extern "C" {
50			#endif
51
52			typedef struct gate_audio_format_class
53			{
54			gate_uint32_t encoding_id;
55			gate_uint32_t samples_per_second;
56			gate_uint16_t channels;
57			gate_uint16_t bits_per_sample;
58			} gate_audio_format_t;
59
60
61			/**
62			* @brief
63			*/
64			GATE_IO_API int gate_compare_audio_format(
65			void const* format1,
66			void const* format2
67			);
68
69
70			/**
71			* @brief
72			*/
73			GATE_IO_API gate_audio_format_t const* gate_audio_format_choose(
74			gate_audio_format_t const* formats,
75			gate_size_t formats_count,
76			gate_uint32_t const* desired_samples_per_second,
77			gate_uint16_t const* desired_channels,
78			gate_uint16_t const* desired_bits_per_sample
79			);
80
81
82			typedef struct gate_audio_sample_class
83			{
84			gate_audio_format_t format;
85			gate_memoryblock_t* data;
86			gate_memoryblock_t* meta_data;
87			gate_uint32_t sample_count; /* amount of stored samples in [data] */
88			gate_int64_t record_time; /* time-index in microseconds from the beginning of the record */
89			} gate_audio_sample_t;
90
91
92			/**
93			* @brief
94			*/
95			GATE_IO_API gate_audio_sample_t* gate_audio_sample_create(
96			gate_audio_sample_t* new_sample,
97			gate_audio_format_t const* format,
98			void const* data, gate_size_t data_size,
99			void const* meta_data, gate_size_t meta_data_size,
100			gate_uint32_t sample_count,
101			gate_int64_t record_time
102			);
103
104
105			/**
106			* @brief
107			*/
108			GATE_IO_API void gate_audio_sample_release(
109			gate_audio_sample_t* sample
110			);
111
112
113			typedef enum gate_audio_device_type_enum
114			{
115			gate_audio_device_unknown = 0,
116			gate_audio_device_input = 1,
117			gate_audio_device_output = 2
118			} gate_audio_device_type_t;
119
120
121		✗	GATE_DELEGATE_DECLARE_2(gate_audio_read_completed, gate_result_t, gate_audio_sample_t*);
122
123		✗	GATE_DELEGATE_DECLARE_2(gate_audio_write_completed, gate_result_t, gate_audio_sample_t const*);
124
125			#define GATE_INTERFACE_NAME_AUDIO_DEVICE GATE_INTERFACE_NAME_OBJECT "/audiodevice"
126
127			GATE_INTERFACE(gate_audio_device)
128			{
129			GATE_METHOD0(char const*, get_interface_name);
130			GATE_METHOD0(void, release);
131			GATE_METHOD0(int, retain);
132
133			GATE_METHOD0(char const*, get_id);
134			GATE_METHOD0(char const*, get_name);
135			GATE_METHOD0(gate_intptr_t, get_handle);
136			GATE_METHOD0(gate_enumint_t, get_device_type);
137			GATE_METHOD2(gate_size_t, get_supported_formats, gate_audio_format_t * format_buffer, gate_size_t format_buffer_count);
138
139			GATE_METHOD2(gate_result_t, open, gate_audio_format_t const* format, gate_size_t sample_count);
140			GATE_METHOD0(gate_result_t, close);
141
142			GATE_METHOD1(gate_result_t, read, gate_audio_sample_t * sample);
143			GATE_METHOD1(gate_result_t, read_async, gate_delegate_t const* completion); /**/
144			GATE_METHOD1(gate_result_t, write, gate_audio_sample_t const* sample);
145			GATE_METHOD2(gate_result_t, write_async, gate_audio_sample_t const* sample, gate_delegate_t const* completion); /**/
146			};
147
148
149			/**
150			* @interface gate_audio_device_t
151			* @implements gate_object_t
152			* @brief Audio I/O device interface
153			*/
154
155			/**
156			* @fn char const* get_id(void)
157			* @memberof gate_audio_device_t
158			* @brief Returns a unique identifier string representing the audio device
159			* @return C-string pointer to identifier
160			*
161			* @fn char const* get_name(void)
162			* @memberof gate_audio_device_t
163			* @brief Returns a human readable name of the audio device
164			* @return C-string pointer to name
165			*
166			* @fn gate_intptr_t get_handle(void)
167			* @memberof gate_audio_device_t
168			* @brief Returns the system native device handle representing the audio device
169			* @return Native handle identifier
170			*
171			* @fn gate_enumint_t get_device_type(void)
172			* @memberof gate_audio_device_t
173			* @brief Returns a device type to identify input and/or output capabilities
174			* @return gate_audio_device_type_t value
175			*
176			* @fn gate_size_t get_supported_formats(gate_audio_format_t * format_buffer, gate_size_t format_buffer_capacity)
177			* @memberof gate_audio_device_t
178			* @brief Fills a buffer with support audio formats that can be processed by an opened device
179			* @param[in,out] format_buffer Pointer to first entry in format buffer array
180			* @param[in] format_buffer_capacity Maximum usable amount of entries in format buffer array
181			* @return Amount of filled entries in buffer
182			*
183			* @fn gate_result_t open(gate_audio_format_t const* format, gate_size_t sample_count)
184			* @memberof gate_audio_device_t
185			* @brief Opens an audio device to process the requested data format
186			* @param[in] format Pointer to format definition of audio samples to process
187			* @param[in] sample_count Default length of a single processed audio record in data-samples count
188			* @return GATE_RESULT_* result code
189			*
190			* @fn gate_result_t close(void)
191			* @memberof gate_audio_device_t
192			* @brief Closes an opened audio device and cancels any active processing tasks
193			* @return GATE_RESULT_* result code
194			*
195			* @fn gate_result_t read(gate_audio_sample_t* sample)
196			* @memberof gate_audio_device_t
197			* @brief Reads a single audio sample from the opened device
198			* @param[in,out] sample Pointer to sample object to be filled with audio data
199			* @return GATE_RESULT_* result code
200			*
201			* @fn gate_result_t read_async(gate_delegate_t const* completion)
202			* @memberof gate_audio_device_t
203			* @brief Reads a single audio sample from the opened device in a background task
204			* @param[in] completion callback to be invoked with the filled sample when reading is complete
205			* @return GATE_RESULT_* result code
206			*
207			* @fn gate_result_t write(gate_audio_sample_t const* sample)
208			* @memberof gate_audio_device_t
209			* @brief Writes a single audio sample to an opened device
210			* @param[in] sample Pointer to audio sample to be sent to the device
211			* @return GATE_RESULT_* result code
212			*
213			* @fn gate_result_t write_async(gate_audio_sample_t const* sample, gate_delegate_t const* completion)
214			* @memberof gate_audio_device_t
215			* @brief Writes a single audio sample to an opened device in a background task
216			* @param[in] sample Pointer to sample to be sent to output device
217			* @param[in] completion Callback to be invoked when the write operation has completed
218			* @return GATE_RESULT_* result code
219			*
220			*/
221
222
223
224			/**
225			* @brief
226			*/
227			#define gate_audio_device_get_id(obj) (obj)->vtbl->get_id((obj))
228
229
230			/**
231			* @brief
232			*/
233			#define gate_audio_device_get_name(obj) (obj)->vtbl->get_name((obj))
234
235
236			/**
237			* @brief
238			*/
239			#define gate_audio_device_get_handle(obj) (obj)->vtbl->get_handle((obj))
240
241
242			/**
243			* @brief
244			*/
245			#define gate_audio_device_get_device_type(obj) (obj)->vtbl->get_device_type((obj))
246
247
248			/**
249			* @brief
250			*/
251			#define gate_audio_device_get_supported_formats(obj, format_buffer, format_buffer_count) \
252			(obj)->vtbl->get_supported_formats((obj), (format_buffer), (format_buffer_count))
253
254			/**
255			* @brief
256			*/
257			#define gate_audio_device_open(obj, format, sample_count) (obj)->vtbl->open((obj), (format), (sample_count))
258
259
260			/**
261			* @brief
262			*/
263			#define gate_audio_device_close(obj) (obj)->vtbl->close((obj))
264
265
266			/**
267			* @brief
268			*/
269			#define gate_audio_device_read(obj, sample) (obj)->vtbl->read((obj), (sample))
270
271
272			/**
273			* @brief
274			*/
275			#define gate_audio_device_read_async(obj, completion) (obj)->vtbl->read_async((obj), (completion))
276
277
278			/**
279			* @brief
280			*/
281			#define gate_audio_device_write(obj, sample) (obj)->vtbl->write((obj), (sample))
282
283
284			/**
285			* @brief
286			*/
287			#define gate_audio_device_write_async(obj, completion) (obj)->vtbl->write_async((obj), (completion))
288
289
290		✗	GATE_DELEGATE_DECLARE_2(gate_audio_devices_enum, gate_audio_device_t*, void*);
291
292
293			/**
294			* @brief
295			*/
296			GATE_IO_API gate_result_t gate_audio_create_wave_reader(gate_stream_t* input, gate_audio_device_t** ptr_reader);
297
298
299			/**
300			* @brief
301			*/
302			GATE_IO_API gate_result_t gate_audio_create_wave_writer(gate_controlstream_t* output, gate_audio_device_t** ptr_writer);
303
304
305			/**
306			* @brief
307			*/
308			GATE_IO_API gate_result_t gate_audio_devices_enum(gate_enumint_t type, gate_delegate_t const* callback, void* param);
309
310
311			/**
312			* @brief
313			*/
314			GATE_IO_API gate_result_t gate_audio_device_by_id(gate_enumint_t type, char const* id, gate_audio_device_t** ptr_device);
315
316
317			#if defined(__cplusplus)
318			}
319			#endif
320
321			#endif
322