#pragma GCC diagnostic pop /* For ISO C99 doesn't support unnamed structs/unions [-Wpedantic] */
#endif
/*
Helper function for initializing a ma_context_config object.
*/
ma_context_config ma_context_config_init(void);
/*
Initializes a context.
The context is used for selecting and initializing the relevant backends.
Note that the location of the context cannot change throughout it's lifetime. Consider allocating
the ma_context object with malloc() if this is an issue. The reason for this is that a pointer
to the context is stored in the ma_device structure.
<backends> is used to allow the application to prioritize backends depending on it's specific
requirements. This can be null in which case it uses the default priority, which is as follows:
- WASAPI
- DirectSound
- WinMM
- Core Audio (Apple)
- sndio
- audio(4)
- OSS
- PulseAudio
- ALSA
- JACK
- AAudio
- OpenSL|ES
- Web Audio / Emscripten
- Null
The context is used for selecting and initializing an appropriate backend and to represent the backend at a more global level than that of an individual
device. There is one context to many devices, and a device is created from a context. A context is required to enumerate devices.
<pConfig> is used to configure the context. Use the logCallback config to set a callback for whenever a
log message is posted. The priority of the worker thread can be set with the threadPriority config.
It is recommended that only a single context is active at any given time because it's a bulky data
structure which performs run-time linking for the relevant backends every time it's initialized.
Parameters
----------
backends (in, optional)
A list of backends to try initializing, in priority order. Can be NULL, in which case it uses default priority order.
Return Value:
MA_SUCCESS if successful; any other error code otherwise.
backendCount (in, optional)
The number of items in `backend`. Ignored if `backend` is NULL.
Thread Safety: UNSAFE
pConfig (in, optional)
The context configuration.
pContext (in)
A pointer to the context object being initialized.
Return Value
------------
MA_SUCCESS if successful; any other error code otherwise.
Thread Safety
-------------
Unsafe. Do not call this function across multiple threads as some backends read and write to global state.
Remarks
-------
When `backends` is NULL, the default priority order will be used. Below is a list of backends in priority order:
The context can be configured via the `pConfig` argument. The config object is initialized with `ma_context_config_init()`. Individual configuration settings
can then be set directly on the structure. See examples below for a usage. Below are the members of the `ma_context_config` object.
logCallback
Callback for handling log messages from miniaudio.
threadPriority
The desired priority to use for the audio thread. Allowable values include the following:
|--------------------------------------|
| Thread Priority |
|--------------------------------------|
| ma_thread_priority_idle |
| ma_thread_priority_lowest |
| ma_thread_priority_low |
| ma_thread_priority_normal |
| ma_thread_priority_high |
| ma_thread_priority_highest (default) |
| ma_thread_priority_realtime |
| ma_thread_priority_default |
|--------------------------------------|
pUserData
A pointer to application-defined data. This can be accessed from the context object directly such as `context.pUserData`.
allocationCallbacks
Structure containing custom allocation callbacks. Leaving this at defaults will cause it to use MA_MALLOC, MA_REALLOC and MA_FREE. These allocation
callbacks will be used for anything tied to the context, including devices.
pulse.pApplicationName
PulseAudio only. The application name to use when initializing the PulseAudio context with `pa_context_new()`.
pulse.pServerName
PulseAudio only. The name of the server to connect to with `pa_context_connect()`.
pulse.tryAutoSpawn
PulseAudio only. Whether or not to try automatically starting the PulseAudio daemon. Defaults to false.
coreaudio.sessionCategory
iOS only. The session category to use for the shared AudioSession instance. Below is a list of allowable values and their Core Audio equivalents.
The name of the client to pass to `jack_client_open()`.
jack.tryStartServer
Whether or not to try auto-starting the JACK server. Defaults to false.
It is recommended that only a single context is active at any given time because it's a bulky data structure which performs run-time linking for the
relevant backends every time it's initialized.
The location of the context cannot change throughout it's lifetime. Consider allocating the `ma_context` object with `malloc()` if this is an issue. The
reason for this is that a pointer to the context is stored in the `ma_device` structure.
Example 1 - Default Initialization
----------------------------------
The example below shows how to initialize the context using the default configuration.
```c
ma_context context;
ma_result result = ma_context_init(NULL, 0, NULL, &context);
if (result != MA_SUCCESS) {
// Error.
}
```
Example 2 - Custom Configuration
--------------------------------
The example below shows how to initialize the context using custom backend priorities and a custom configuration. In this hypothetical example, the program
wants to prioritize ALSA over PulseAudio on Linux. They also want to avoid using the WinMM backend on Windows because it's latency is too high. They also
want an error to be returned if no valid backend is available which they achieve by excluding the Null backend.
For the configuration, the program wants to capture any log messages so they can, for example, route it to a log file and user interface.
