CRI ADX  Last Updated: 2024-07-17 10:47 p
CriAtom WASAPI API

Data Structures

struct  CriAtomConfigTag_WASAPI
 Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtom_Initialize_WASAPI function.
More...
 
struct  CriAtomExConfigTag_WASAPI
 Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtomEx_Initialize_WASAPI function.
More...
 

Macros

#define criAtom_SetDefaultConfig_WASAPI(p_config)
 Assign the default values to the configuration structure used for the library's initialization. More...
 
#define criAtomEx_SetDefaultConfig_WASAPI(p_config)
 Assign the default values to the configuration structure used for the library's initialization. More...
 

Typedefs

typedef struct CriAtomConfigTag_WASAPI CriAtomConfig_WASAPI
 Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtom_Initialize_WASAPI function.
More...
 
typedef void(* CriAtomAudioEndpointCbFunc_WASAPI) (void *object, IMMDevice *device)
 Audio endpoint enumeration callback. More...
 
typedef void(* CriAtomDeviceUpdateCbFunc_WASAPI) (void *object)
 Device update notification callback. More...
 
typedef struct CriAtomExConfigTag_WASAPI CriAtomExConfig_WASAPI
 Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtomEx_Initialize_WASAPI function.
More...
 

Functions

CriSint32 criAtom_CalculateWorkSize_WASAPI (const CriAtomConfig_WASAPI *config)
 Calculate the size of the work buffer required to initialize the library. More...
 
void criAtom_Initialize_WASAPI (const CriAtomConfig_WASAPI *config, void *work, CriSint32 work_size)
 Library initialization. More...
 
void criAtom_Finalize_WASAPI (void)
 Finalize the library. More...
 
CriBool criAtom_GetAudioClientMixFormat_WASAPI (WAVEFORMATEXTENSIBLE *format)
 Get the mixer format. More...
 
CriBool criAtom_GetAudioClientIsFormatSupported_WASAPI (const WAVEFORMATEX *format)
 Check whether the specified format is usable or not. More...
 
void criAtom_SetAudioClientShareMode_WASAPI (AUDCLNT_SHAREMODE mode)
 Sharing mode specification. More...
 
AUDCLNT_SHAREMODE criAtom_GetAudioClientShareMode_WASAPI (void)
 Obtaining a shared mode. More...
 
void criAtom_SetAudioClientFormat_WASAPI (const WAVEFORMATEX *format)
 Output format specification. More...
 
void criAtom_SetAudioClientBufferDuration_WASAPI (REFERENCE_TIME ref_time)
 Set the buffering time. More...
 
IAudioClient * criAtom_GetAudioClient_WASAPI (void)
 Get the AudioClient. More...
 
CriBool criAtom_IsDeviceInvalidated_WASAPI (void)
 Check if the audio device is disabled. More...
 
void criAtom_SetDeviceId_WASAPI (CriAtomSoundRendererType type, LPCWSTR device_id)
 Set sound device. More...
 
CriSint32 criAtom_EnumAudioEndpoints_WASAPI (CriAtomAudioEndpointCbFunc_WASAPI callback, void *object)
 Enumerate audio endpoints. More...
 
void criAtom_SetDeviceUpdateCallback_WASAPI (CriAtomDeviceUpdateCbFunc_WASAPI callback, void *object)
 Register device update notification. More...
 
void criAtom_SetSpatialAudioEnabled_WASAPI (CriAtomSoundRendererType type, CriBool sw)
 Enabling the Spatial Audio feature. More...
 
CriBool criAtom_IsSpatialAudioEnabled_WASAPI (CriAtomSoundRendererType type)
 Check if the Spatial Audio feature is enabled. More...
 
CriSint32 criAtomEx_CalculateWorkSize_WASAPI (const CriAtomExConfig_WASAPI *config)
 Calculate the size of the work buffer required to initialize the library. More...
 
void criAtomEx_Initialize_WASAPI (const CriAtomExConfig_WASAPI *config, void *work, CriSint32 work_size)
 Library initialization. More...
 
void criAtomEx_Finalize_WASAPI (void)
 Finalize the library. More...
 

Detailed Description

Macro Definition Documentation

◆ criAtom_SetDefaultConfig_WASAPI

#define criAtom_SetDefaultConfig_WASAPI (   p_config)
Value:
{ \
criAtom_SetDefaultConfig(&(p_config)->atom); \
criAtomAsr_SetDefaultConfig(&(p_config)->asr); \
criAtomHcaMx_SetDefaultConfig(&(p_config)->hca_mx); \
}

Assign the default values to the configuration structure used for the library's initialization.

Parameters
[out]p_configPointer to the configuration structure used for the library's initialization.
Description:
Assign the default values to the configuration structure (CriAtomConfig_WASAPI) that is passed to the criAtom_Initialize_WASAPI function.
Attention
This macro is for the low level API.
When using the functions of the AtomEx layer, call the criAtomEx_SetDefaultConfig_WASAPI macro instead.
See also
CriAtomConfig_WASAPI

◆ criAtomEx_SetDefaultConfig_WASAPI

#define criAtomEx_SetDefaultConfig_WASAPI (   p_config)
Value:
{ \
criAtomEx_SetDefaultConfig(&(p_config)->atom_ex); \
(p_config)->atom_ex.thread_model = CRIATOMEX_THREAD_MODEL_MULTI_WITH_SONICSYNC; \
criAtomExAsr_SetDefaultConfig(&(p_config)->asr); \
criAtomExHcaMx_SetDefaultConfig(&(p_config)->hca_mx); \
}
#define criAtomExAsr_SetDefaultConfig(p_config)
Set default parameters to CriAtomExAsrConfig.
Definition: cri_le_atom_asr.h:2079
@ CRIATOMEX_THREAD_MODEL_MULTI_WITH_SONICSYNC
Multi-threaded low latency output.
Definition: cri_le_atom_ex.h:1248

Assign the default values to the configuration structure used for the library's initialization.

Parameters
[out]p_configPointer to the configuration structure used for the library's initialization.
Description:
Assign the default values to the configuration structure (CriAtomExConfig_WASAPI) that is passed to the criAtomEx_Initialize_WASAPI function.
See also
CriAtomExConfig_WASAPI

Typedef Documentation

◆ CriAtomConfig_WASAPI

Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtom_Initialize_WASAPI function.

Attention
This structure is used for low level API.
When using the functions of the AtomEx layer, use the CriAtomExConfig_WASAPI structure instead.
See also
criAtom_Initialize_WASAPI, criAtom_SetDefaultConfig_WASAPI

◆ CriAtomAudioEndpointCbFunc_WASAPI

typedef void( * CriAtomAudioEndpointCbFunc_WASAPI) (void *object, IMMDevice *device)

Audio endpoint enumeration callback.

Parameters
[in]objectUser Object
[in]deviceIMMDevice instance
Description:
The type of the callback function used to notify the audio endpoint.
By registering this function type callback function in the criAtom_EnumAudioEndpoints_WASAPI function,
it is possible to receive an IMMDevice instance via a callback.
Attention
IMMDevice instances MUST NOT be discarded within the callback function.
See also
criAtom_EnumAudioEndpoints_WASAPI

◆ CriAtomDeviceUpdateCbFunc_WASAPI

typedef void( * CriAtomDeviceUpdateCbFunc_WASAPI) (void *object)

Device update notification callback.

Parameters
[in]objectUser Object
Description:
The type of callback function used for device update notification.
By registering this function type callback function in the criAtom_SetDeviceUpdateCallback_WASAPI function, it is possible to receive notification via callback when the device is updated.
See also
criAtom_SetDeviceUpdateCallback_WASAPI

◆ CriAtomExConfig_WASAPI

Configuration structure used for the initialization of the Atom libraryThis configuration structure is used to specify the behavior of the CRI Atom library.
It is passed as an argument to the criAtomEx_Initialize_WASAPI function.

See also
criAtomEx_Initialize_WASAPI, criAtomEx_SetDefaultConfig_WASAPI

Function Documentation

◆ criAtom_CalculateWorkSize_WASAPI()

CriSint32 criAtom_CalculateWorkSize_WASAPI ( const CriAtomConfig_WASAPI config)

Calculate the size of the work buffer required to initialize the library.

Parameters
[in]configConfiguration structure for initialization
Returns
CriSint32 Work buffer size
Description:
This function retrieves the size of the work buffer needed to use the library.
Remarks:
The work buffer size needed by the library's initialization depends on the values of the parameters in the CriAtomConfig_WASAPI structure.

The information passed in the config argument is only referenced within this function.
Therefore the memory it uses can be released after executing the function.
Attention
This function is for the low level API.
When using the functions of the AtomEx layer, call criAtomEx_CalculateWorkSize_WASAPI instead.
See also
CriAtomConfig_WASAPI, criAtom_Initialize_WASAPI

◆ criAtom_Initialize_WASAPI()

void criAtom_Initialize_WASAPI ( const CriAtomConfig_WASAPI config,
void *  work,
CriSint32  work_size 
)

Library initialization.

Parameters
[in]configConfiguration structure for initialization
[in]workWork buffer
[in]work_sizeWork buffer size
Description:
Initializes the library.
In order to be able to use the features of the library, you must first call this function.
(Once this function is called, the features of the library are available until the criAtom_Finalize_WASAPI function is called.)

To initialize the library, you must allocate a memory area (work buffer) that will be used internally by the library.
The size of the work buffer needed by the library depends on the values of the parameters in the configuration structure used for initialization.
Use the criAtom_CalculateWorkSize_WASAPI function to calculate the work buffer size.
Remarks:
If an allocator has already been registered with the criAtom_SetUserAllocator macro, the work buffer size does not need to be specified.
(By passing NULL for work and 0 for work_size, the amount of memory corresponding to the work buffer size is dynamically allocated by the registered allocator.)
The information passed in the config argument is only referenced within this function.
Therefore the memory it uses can be released after executing the function.
Attention
This function calls the following functions internally:

Therefore, if you call this function, do not call the functions listed above.

If you call this function, you must always call the criAtom_Finalize_WASAPI function later.
Do not call this function again until you have called the criAtom_Finalize_WASAPI function.

This function is for the low level API.
When using the functions of the AtomEx layer, call criAtomEx_Initialize_WASAPI instead.

See also
CriAtomConfig_WASAPI, criAtom_Finalize_WASAPI, criAtom_SetUserAllocator, criAtom_CalculateWorkSize_WASAPI

◆ criAtom_Finalize_WASAPI()

void criAtom_Finalize_WASAPI ( void  )

Finalize the library.

Description:
This function finalizes the library.
Attention
This function calls the following functions internally:

Therefore, if you call this function, do not call the functions above.

This function cannot be called before the criAtom_Initialize_WASAPI function is called.

This function is for the low level API.
When using the functions of the AtomEx layer, call criAtomEx_Finalize_WASAPI instead.

See also
criAtom_Initialize_WASAPI

◆ criAtom_GetAudioClientMixFormat_WASAPI()

CriBool criAtom_GetAudioClientMixFormat_WASAPI ( WAVEFORMATEXTENSIBLE *  format)

Get the mixer format.

Parameters
[out]formatMixer format
Returns
CriBool Was the mixer format acquired? (CRI_TRUE = Success, CRI_FALSE = Failure)
Description:
Gets the mixer format used in Shared Mode.
Remarks:
This function is a wrapper around the IAudioClient::GetMixFormat function.
When it is called, an AudioClient is created within the function and the GetMixFormat function is executed.
Attention
This function can only be used before the library's initialization.

The usable formats differ between Shared Mode and Exclusive Mode.
The WAVEFORMATEXTENSIBLE structure returned by this function corresponds to the IEEE float PCM data format, but this format is mostly unusable in Exclusive Mode.

◆ criAtom_GetAudioClientIsFormatSupported_WASAPI()

CriBool criAtom_GetAudioClientIsFormatSupported_WASAPI ( const WAVEFORMATEX *  format)

Check whether the specified format is usable or not.

Parameters
[in]formatFormat to be used
Returns
CriBool Is the specified format usable? (CRI_TRUE = Usable, CRI_FALSE = Not Usable)
Description:
Checks whether the format specified in the argument is usable in Exclusive Mode or not.
Remarks:
This function is a wrapper around the IAudioClient::IsFormatSupported function.
When it is called, an AudioClient is created within the function and the IsFormatSupported function is executed.
Attention
This function can only be used before the library's initialization.

On some devices and for some parameters, the WASAPI initialization may fail even if this function returns successfully.
If the library fails to initialize even when this function returns CRI_TRUE, change the specified format or use the Shared Mode.

◆ criAtom_SetAudioClientShareMode_WASAPI()

void criAtom_SetAudioClientShareMode_WASAPI ( AUDCLNT_SHAREMODE  mode)

Sharing mode specification.

Parameters
[in]modeMode to be used
Description:
Specifies whether to use WASAPI in Shared Mode or Exclusive Mode.

If this function is not executed (or if it is executed by specifying AUDCLNT_SHAREMODE_SHARED), the Atom library will initialize WASAPI in Shared Mode.
If this function is executed by specifying AUDCLNT_SHAREMODE_EXCLUSIVE, the Atom library will initialize WASAPI in Exclusive Mode.
Attention
You must execute this function before initializing the library.

To use the Exclusive Mode, the mode must be specified with this function and the format must also be specified via the criAtom_SetAudioClientFormat_WASAPI function.
See also
criAtom_SetAudioClientFormat_WASAPI

◆ criAtom_GetAudioClientShareMode_WASAPI()

AUDCLNT_SHAREMODE criAtom_GetAudioClientShareMode_WASAPI ( void  )

Obtaining a shared mode.

Returns
AUDCLNT_SHAREMODE shared mode
説明:
Gets the currently specified sharing mode.
See also
criAtom_SetAudioClientShareMode_WASAPI

◆ criAtom_SetAudioClientFormat_WASAPI()

void criAtom_SetAudioClientFormat_WASAPI ( const WAVEFORMATEX *  format)

Output format specification.

Description:
Parameters
[in]formatFormat to be used
Description:
Specifies the format to be used in Exclusive Mode.
Remarks:
The format specified is passed to the IAudioClient::Initialize function.
Attention
You must call this function before initializing the library.

To use the Exclusive Mode, the format must be specified with this function and the mode must also be specified via the criAtom_SetAudioClientShareMode_WASAPI function.
See also
criAtom_SetAudioClientShareMode_WASAPI

◆ criAtom_SetAudioClientBufferDuration_WASAPI()

void criAtom_SetAudioClientBufferDuration_WASAPI ( REFERENCE_TIME  ref_time)

Set the buffering time.

Parameters
[in]ref_timeBuffering time
Description:
Specifies the buffering time (before the WASAPI initialization).
The Atom library will allocate a sound buffer large enough to hold data for the amount of time specified by this function.
Remarks:
The buffering time is passed to the IAudioClient::Initialize function.

If you specify 0 for ref_time or if you do not use this function, the Atom library will calculate the appropriate buffering time based on the server process frequency specified during initialization.
If this function is not used, the Atom library will calculate the appropriate buffering time based on the server process frequency specified during initialization.

Because of the variability in hardware performance in PC environments, the default amount of buffering is set higher to match the worst-performing hardware.
(The default state has a buffer of 4V)
Attention
You must call this function before initializing the library.

If the buffering time is too short, problems such as audio dropouts may occur.

Since the amount of buffering required in a PC environment varies depending on the hardware, using this function may result in sound interruptions in some user environments, even if it works well in the test environment.
Therefore, if you want to change the amount of buffering, consider providing a mechanism (such as an options screen) that allows the user to change the set value.

◆ criAtom_GetAudioClient_WASAPI()

IAudioClient* criAtom_GetAudioClient_WASAPI ( void  )

Get the AudioClient.

Returns
IAudioClient AudioClient
Description:
Get the AudioClient created within the Atom library.
Remarks:
This function will return NULL if executed on a PC that does not have a sound device.
Note:
You must initialize the library before calling this function.

◆ criAtom_IsDeviceInvalidated_WASAPI()

CriBool criAtom_IsDeviceInvalidated_WASAPI ( void  )

Check if the audio device is disabled.

Returns
CriBool Has the device been disabled? (CRI_TRUE = Disabled, CRI_FALSE = Operating Normally)
Description:
Returns whether or not the audio device has been disabled.
Remarks:
This function only returns CRI_TRUE when the sound device has been disabled while the application was running.
This function will return CRI_FALSE if executed on a PC that does not have a sound device at all.
(Use the criAtom_GetAudioClient_WASAPI function to check whether or not a sound device exists.)
See also
criAtom_GetAudioClient_WASAPI

◆ criAtom_SetDeviceId_WASAPI()

void criAtom_SetDeviceId_WASAPI ( CriAtomSoundRendererType  type,
LPCWSTR  device_id 
)

Set sound device.

Parameters
[in]typeSound renderer type
[in]device_idDevice ID
Description:
Link the sound renderer type to the sound device.

If set the device ID for the sound renderer with this function, all sounds specified by specifying the sound renderer will be output from the sound device that matches the specified ID.
The following values can be specified for "type".
  • CRIATOM_SOUND_RENDERER_HW1 (same value as CRIATOM_SOUND_RENDERER_NATIVE)
  • CRIATOM_SOUND_RENDERER_HW2
  • CRIATOM_SOUND_RENDERER_HW3
  • CRIATOM_SOUND_RENDERER_HW4

If NULL or a character string of length 0 is specified for "device_id", the link between the sound renderer and the device ID is canceled. (The behavior will change as the audio output from the default device.)

Remarks:
The ID of the sound device needs to be acquired with IMMDevice::GetId.
If a sound device that matches the specified ID can not be found, the sound that was played with the device specified is output from the default device.

◆ criAtom_EnumAudioEndpoints_WASAPI()

CriSint32 criAtom_EnumAudioEndpoints_WASAPI ( CriAtomAudioEndpointCbFunc_WASAPI  callback,
void *  object 
)

Enumerate audio endpoints.

Parameters
[in]callbackAudio endpoint callback function
[in]objectUser Object
Returns
CriSint32 Number of enumerated ACB handles
Description:
Enumerate audio endpoints.

When this function is executed, the callback function set in "call_back" is called up by the number of audio endpoints.
An IMMDevice instance is passed as an argument to the callback function.
Remarks:
The value set for "object" is passed as the argument of the callback function.
For other arguments of the callback function, see the explanation of CriAtomAudioEndpointCbFunc_WASAPI .

The return value is the number of enumerated audio endpoints (the number of times the registered callback function was called).
If there is no audio endpoint, this function returns 0.
If an error occurs, -1 is returned.
Attention
IMMDevice instances MUST NOT be discarded within the callback function.
See also
CriAtomAudioEndpointCbFunc_WASAPI

◆ criAtom_SetDeviceUpdateCallback_WASAPI()

void criAtom_SetDeviceUpdateCallback_WASAPI ( CriAtomDeviceUpdateCbFunc_WASAPI  callback,
void *  object 
)

Register device update notification.

Parameters
[in]callbackDevice Update callback function
[in]objectUser Object
Description:
Set up a callback to receive device update notifications.

When this function is executed, when the device is updated, the callback function set with the first argument (callback) will be called.
Remarks:
The value set for the second argument (object) is passed as the argument of the callback function.
See also
CriAtomAudioEndpointCbFunc_WASAPI

◆ criAtom_SetSpatialAudioEnabled_WASAPI()

void criAtom_SetSpatialAudioEnabled_WASAPI ( CriAtomSoundRendererType  type,
CriBool  sw 
)

Enabling the Spatial Audio feature.

Parameters
[in]typeSound Renderer Type
[in]swEnable or disable the function (CRI_TRUE = enable, CRI_FALSE = disable)
Description:
Enables the Spatial Audio feature (Microsoft Spatial Sound).
The argument type specifies the sound renderer that enables (or disables) the spaced audio feature.
Remarks:
In the current library, the Spacial Audio feature is enabled by default.
Therefore, there is no need to explicitly call this function unless you wish to disable the Spacial Audio function.

◆ criAtom_IsSpatialAudioEnabled_WASAPI()

CriBool criAtom_IsSpatialAudioEnabled_WASAPI ( CriAtomSoundRendererType  type)

Check if the Spatial Audio feature is enabled.

Parameters
[in]typeSound Renderer Type
Returns
CriBool Whether the function is enabled or not (CRI_TRUE = enabled, CRI_FALSE = disabled)
Description:
Checks if the Spacial Audio feature is enabled.
The type argument specifies the sound renderer to be checked to see if the spaced audio feature is enabled.

◆ criAtomEx_CalculateWorkSize_WASAPI()

CriSint32 criAtomEx_CalculateWorkSize_WASAPI ( const CriAtomExConfig_WASAPI config)

Calculate the size of the work buffer required to initialize the library.

Parameters
[in]configConfiguration structure for initialization
Returns
CriSint32 Work buffer size
Description:
This function retrieves the size of the work buffer needed to use the library.
Remarks:
The work buffer size needed by the library's initialization depends on the values of the parameters in the CriAtomExConfig_WASAPI structure.
The information passed in the config argument is only referenced within this function.
Therefore the memory it uses can be released after executing the function.
Attention
If you set the value to the acf_info member of the CriAtomExConfig_WASAPI structure, this function fails and returns -1.
When registering ACF data within the initialization process, you will need to allocate memory using a memory allocator by the ADX system instead of using this function.
See also
CriAtomExConfig_WASAPI, criAtomEx_Initialize_WASAPI

◆ criAtomEx_Initialize_WASAPI()

void criAtomEx_Initialize_WASAPI ( const CriAtomExConfig_WASAPI config,
void *  work,
CriSint32  work_size 
)

Library initialization.

Parameters
[in]configConfiguration structure for initialization
[in]workWork area
[in]work_sizeWork area size
Description:
Initializes the library.
In order to be able to use the features of the library, you must first call this function.
(Once this function is called, the features of the library are available until the criAtomEx_Finalize_WASAPI function is called.)

To initialize the library, you must allocate the memory (work buffer) used internally by the library.
The size of the work buffer needed by the library depends on the values of the parameters in the configuration structure used for initialization.
Use the criAtomEx_CalculateWorkSize_WASAPI function to calculate the size of the work buffer.
Remarks:
If an allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to specify a work buffer to this function.
(By passing NULL for work and 0 for work_size, the amount of memory corresponding to the work buffer size is dynamically allocated by the registered allocator.)
The information passed in the config argument is only referenced within this function.
Therefore the memory it uses can be released after executing the function.
Attention
This function internally calls:

Therefore, if you call this function, do not call the functions listed above.

If you call this function, you must always call the criAtomEx_Finalize_WASAPI function later.
Do call this function again before having called criAtomEx_Finalize_WASAPI.

See also
CriAtomExConfig_WASAPI, criAtomEx_Finalize_WASAPI, criAtomEx_SetUserAllocator, criAtomEx_CalculateWorkSize_WASAPI

◆ criAtomEx_Finalize_WASAPI()

void criAtomEx_Finalize_WASAPI ( void  )

Finalize the library.

Description:
This function finalizes the library.
Attention
This function internally calls:

Therefore, if you call this function, do not call the functions above.

This function cannot be executed before the criAtomEx_Initialize_WASAPI function is called.

See also
criAtomEx_Initialize_WASAPI