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

结构体

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.
更多...
 
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.
更多...
 

宏定义

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

类型定义

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.
更多...
 
typedef void(* CriAtomAudioEndpointCbFunc_WASAPI) (void *object, IMMDevice *device)
 Audio endpoint enumeration callback 更多...
 
typedef void(* CriAtomDeviceUpdateCbFunc_WASAPI) (void *object)
 Device update notification callback 更多...
 
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.
更多...
 

函数

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

详细描述



宏定义说明

◆ criAtom_SetDefaultConfig_WASAPI

#define criAtom_SetDefaultConfig_WASAPI (   p_config)
值:
{ \
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.

参数
[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.
注意
This macro is for the low level API.
When using the functions of the AtomEx layer, call the criAtomEx_SetDefaultConfig_WASAPI macro instead.
参见
CriAtomConfig_WASAPI

◆ criAtomEx_SetDefaultConfig_WASAPI

#define criAtomEx_SetDefaultConfig_WASAPI (   p_config)
值:
{ \
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.

参数
[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.
参见
CriAtomExConfig_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.

注意
This structure is used for low level API.
When using the functions of the AtomEx layer, use the CriAtomExConfig_WASAPI structure instead.
参见
criAtom_Initialize_WASAPI, criAtom_SetDefaultConfig_WASAPI

◆ CriAtomAudioEndpointCbFunc_WASAPI

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

Audio endpoint enumeration callback

参数
[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.
注意
IMMDevice instances MUST NOT be discarded within the callback function.
参见
criAtom_EnumAudioEndpoints_WASAPI

◆ CriAtomDeviceUpdateCbFunc_WASAPI

typedef void( * CriAtomDeviceUpdateCbFunc_WASAPI) (void *object)

Device update notification callback

参数
[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.
参见
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.

参见
criAtomEx_Initialize_WASAPI, criAtomEx_SetDefaultConfig_WASAPI

函数说明

◆ criAtom_CalculateWorkSize_WASAPI()

CriSint32 criAtom_CalculateWorkSize_WASAPI ( const CriAtomConfig_WASAPI config)

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

参数
[in]configConfiguration structure for initialization
返回
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.
注意
This function is for the low level API.
When using the functions of the AtomEx layer, call criAtomEx_CalculateWorkSize_WASAPI instead.
参见
CriAtomConfig_WASAPI, criAtom_Initialize_WASAPI

◆ criAtom_Initialize_WASAPI()

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

Library initialization

参数
[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.
注意
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.

参见
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.
注意
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.

参见
criAtom_Initialize_WASAPI

◆ criAtom_GetAudioClientMixFormat_WASAPI()

CriBool criAtom_GetAudioClientMixFormat_WASAPI ( WAVEFORMATEXTENSIBLE *  format)

Get the mixer format

参数
[out]formatMixer format
返回
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.
注意
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

参数
[in]formatFormat to be used
返回
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.
注意
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

参数
[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.
注意
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.
参见
criAtom_SetAudioClientFormat_WASAPI

◆ criAtom_GetAudioClientShareMode_WASAPI()

AUDCLNT_SHAREMODE criAtom_GetAudioClientShareMode_WASAPI ( void  )

Obtaining a shared mode

返回
AUDCLNT_SHAREMODE shared mode
説明:
Gets the currently specified sharing mode.
参见
criAtom_SetAudioClientShareMode_WASAPI

◆ criAtom_SetAudioClientFormat_WASAPI()

void criAtom_SetAudioClientFormat_WASAPI ( const WAVEFORMATEX *  format)

Output format specification

Description:
参数
[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.
注意
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.
参见
criAtom_SetAudioClientShareMode_WASAPI

◆ criAtom_SetAudioClientBufferDuration_WASAPI()

void criAtom_SetAudioClientBufferDuration_WASAPI ( REFERENCE_TIME  ref_time)

Set the buffering time

参数
[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)
注意
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

返回
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

返回
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.)
参见
criAtom_GetAudioClient_WASAPI

◆ criAtom_SetDeviceId_WASAPI()

void criAtom_SetDeviceId_WASAPI ( CriAtomSoundRendererType  type,
LPCWSTR  device_id 
)

Set sound device

参数
[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

参数
[in]callbackAudio endpoint callback function
[in]objectUser Object
返回
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.
注意
IMMDevice instances MUST NOT be discarded within the callback function.
参见
CriAtomAudioEndpointCbFunc_WASAPI

◆ criAtom_SetDeviceUpdateCallback_WASAPI()

void criAtom_SetDeviceUpdateCallback_WASAPI ( CriAtomDeviceUpdateCbFunc_WASAPI  callback,
void *  object 
)

Register device update notification

参数
[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.
参见
CriAtomAudioEndpointCbFunc_WASAPI

◆ criAtom_SetSpatialAudioEnabled_WASAPI()

void criAtom_SetSpatialAudioEnabled_WASAPI ( CriAtomSoundRendererType  type,
CriBool  sw 
)

Enabling the Spatial Audio feature

参数
[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

参数
[in]typeSound Renderer Type
返回
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

参数
[in]configConfiguration structure for initialization
返回
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.
注意
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.
参见
CriAtomExConfig_WASAPI, criAtomEx_Initialize_WASAPI

◆ criAtomEx_Initialize_WASAPI()

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

Library initialization

参数
[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.
注意
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.

参见
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.
注意
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.

参见
criAtomEx_Initialize_WASAPI