CriAtom WASAPI API


構成

struct  CriAtomConfigTag_WASAPI
 Atomライブラリ初期化用コンフィグ構造体 [詳細]
struct  CriAtomExConfigTag_WASAPI
 Atomライブラリ初期化用コンフィグ構造体 [詳細]

マクロ定義

#define criAtom_SetDefaultConfig_WASAPI(p_config)
 ライブラリ初期化用コンフィグ構造体にデフォルト値をセット
#define criAtomEx_SetDefaultConfig_WASAPI(p_config)
 ライブラリ初期化用コンフィグ構造体にデフォルト値をセット

型定義

typedef CriAtomConfigTag_WASAPI CriAtomConfig_WASAPI
 Atomライブラリ初期化用コンフィグ構造体
typedef void(CRIAPI *) CriAtomAudioEndpointCbFunc_WASAPI (void *object, IMMDevice *device)
 オーディオエンドポイント列挙コールバック
typedef void(CRIAPI *) CriAtomDeviceUpdateCbFunc_WASAPI (void *object)
 デバイス更新通知コールバック
typedef CriAtomExConfigTag_WASAPI CriAtomExConfig_WASAPI
 Atomライブラリ初期化用コンフィグ構造体

関数

CriSint32 CRIAPI criAtom_CalculateWorkSize_WASAPI (const CriAtomConfig_WASAPI *config)
 ライブラリ初期化用ワーク領域サイズの計算
void CRIAPI criAtom_Initialize_WASAPI (const CriAtomConfig_WASAPI *config, void *work, CriSint32 work_size)
 ライブラリの初期化
void CRIAPI criAtom_Finalize_WASAPI (void)
 ライブラリの終了
CriBool CRIAPI criAtom_GetAudioClientMixFormat_WASAPI (WAVEFORMATEXTENSIBLE *format)
 ミキサフォーマットの取得
CriBool CRIAPI criAtom_GetAudioClientIsFormatSupported_WASAPI (const WAVEFORMATEX *format)
 指定したフォーマットが利用可能かどうかチェック
void CRIAPI criAtom_SetAudioClientShareMode_WASAPI (AUDCLNT_SHAREMODE mode)
 共有方式の指定
void CRIAPI criAtom_SetAudioClientFormat_WASAPI (const WAVEFORMATEX *format)
 出力フォーマットの指定
void CRIAPI criAtom_SetAudioClientBufferDuration_WASAPI (REFERENCE_TIME ref_time)
 バッファリング時間の指定
IAudioClient *CRIAPI criAtom_GetAudioClient_WASAPI (void)
 AudioClientの取得
CriBool CRIAPI criAtom_IsDeviceInvalidated_WASAPI (void)
 デバイスが無効化されたかどうかのチェック
void CRIAPI criAtom_SetDeviceId_WASAPI (CriAtomSoundRendererType type, LPCWSTR device_id)
 サウンドデバイスの指定
CriSint32 CRIAPI criAtom_EnumAudioEndpoints_WASAPI (CriAtomAudioEndpointCbFunc_WASAPI callback, void *object)
 オーディオエンドポイントの列挙
void CRIAPI criAtom_SetDeviceUpdateCallback_WASAPI (CriAtomDeviceUpdateCbFunc_WASAPI callback, void *object)
 デバイス更新通知の登録
CriSint32 CRIAPI criAtomEx_CalculateWorkSize_WASAPI (const CriAtomExConfig_WASAPI *config)
 ライブラリ初期化用ワーク領域サイズの計算
void CRIAPI criAtomEx_Initialize_WASAPI (const CriAtomExConfig_WASAPI *config, void *work, CriSint32 work_size)
 ライブラリの初期化
void CRIAPI criAtomEx_Finalize_WASAPI (void)
 ライブラリの終了

マクロ定義

#define criAtom_SetDefaultConfig_WASAPI ( p_config   ) 

値:

{                                                           \
    criAtom_SetDefaultConfig(&(p_config)->atom);            \
    criAtomAsr_SetDefaultConfig(&(p_config)->asr);          \
    criAtomHcaMx_SetDefaultConfig(&(p_config)->hca_mx);     \
}
ライブラリ初期化用コンフィグ構造体にデフォルト値をセット

引数:
[out] p_config 初期化用コンフィグ構造体へのポインタ
説明:
criAtom_Initialize_WASAPI 関数に設定するコンフィグ構造体 ( CriAtomConfig_WASAPI )に、デフォルトの値をセットします。
注意:
本マクロは下位レイヤ向けのAPIです。
AtomExレイヤの機能を利用する際には、本マクロの代わりに criAtomEx_SetDefaultConfig_WASAPI マクロをご利用ください。
参照:
CriAtomConfig_WASAPI

#define criAtomEx_SetDefaultConfig_WASAPI ( p_config   ) 

値:

{                                                           \
    criAtomEx_SetDefaultConfig(&(p_config)->atom_ex);       \
    criAtomExAsr_SetDefaultConfig(&(p_config)->asr);        \
    criAtomExHcaMx_SetDefaultConfig(&(p_config)->hca_mx);   \
}
ライブラリ初期化用コンフィグ構造体にデフォルト値をセット

引数:
[out] p_config 初期化用コンフィグ構造体へのポインタ
説明:
criAtomEx_Initialize_WASAPI 関数に設定するコンフィグ構造体 ( CriAtomExConfig_WASAPI )に、デフォルトの値をセットします。
参照:
CriAtomExConfig_WASAPI


型定義

typedef struct CriAtomConfigTag_WASAPI CriAtomConfig_WASAPI

Atomライブラリ初期化用コンフィグ構造体

CRI Atomライブラリの動作仕様を指定するための構造体です。
criAtom_Initialize_WASAPI 関数の引数に指定します。

注意:
本構造体は下位レイヤ向けのAPIです。
AtomExレイヤの機能を利用する際には、本構造体の代わりに CriAtomExConfig_WASAPI 構造体をご利用ください。
参照:
criAtom_Initialize_WASAPI, criAtom_SetDefaultConfig_WASAPI

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

オーディオエンドポイント列挙コールバック

引数:
[in] object ユーザ指定オブジェクト
[in] device IMMDeviceインスタンス
説明:
オーディオエンドポイントの通知に使用される、コールバック関数の型です。
criAtom_EnumAudioEndpoints_WASAPI 関数に本関数型のコールバック関数を登録することで、 IMMDeviceインスタンスをコールバック経由で受け取ることが可能です。
注意:
IMMDeviceインスタンスをコールバック関数内で破棄してはいけません。
参照:
criAtom_EnumAudioEndpoints_WASAPI

typedef void(CRIAPI *) CriAtomDeviceUpdateCbFunc_WASAPI(void *object)

デバイス更新通知コールバック

引数:
[in] object ユーザ指定オブジェクト
説明:
デバイスの更新通知に使用される、コールバック関数の型です。
criAtom_SetDeviceUpdateCallback_WASAPI 関数に本関数型のコールバック関数を登録することで、 デバイスが更新された際にコールバック経由で通知を受け取ることが可能です。
参照:
criAtom_SetDeviceUpdateCallback_WASAPI

typedef struct CriAtomExConfigTag_WASAPI CriAtomExConfig_WASAPI

Atomライブラリ初期化用コンフィグ構造体

CRI Atomライブラリの動作仕様を指定するための構造体です。
criAtomEx_Initialize_WASAPI 関数の引数に指定します。

参照:
criAtomEx_Initialize_WASAPI, criAtomEx_SetDefaultConfig_WASAPI


関数

CriSint32 CRIAPI criAtom_CalculateWorkSize_WASAPI ( const CriAtomConfig_WASAPI config  ) 

ライブラリ初期化用ワーク領域サイズの計算

引数:
[in] config 初期化用コンフィグ構造体
戻り値:
CriSint32 ワーク領域サイズ
説明:
ライブラリを使用するために必要な、ワーク領域のサイズを取得します。
備考:
ライブラリが必要とするワーク領域のサイズは、ライブラリ初期化用コンフィグ 構造体( CriAtomConfig_WASAPI )の内容によって変化します。

引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。
注意:
本関数は下位レイヤ向けのAPIです。
AtomExレイヤの機能を利用する際には、本関数の代わりに criAtomEx_CalculateWorkSize_WASAPI 関数をご利用ください。
参照:
CriAtomConfig_WASAPI, criAtom_Initialize_WASAPI

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

ライブラリの初期化

引数:
[in] config 初期化用コンフィグ構造体
[in] work ワーク領域
[in] work_size ワーク領域サイズ
説明:
ライブラリを初期化します。
ライブラリの機能を利用するには、必ずこの関数を実行する必要があります。
(ライブラリの機能は、本関数を実行後、 criAtom_Finalize_WASAPI 関数を実行するまでの間、 利用可能です。)

ライブラリを初期化する際には、ライブラリが内部で利用するためのメモリ領域(ワーク領域) を確保する必要があります。
ライブラリが必要とするワーク領域のサイズは、初期化用コンフィグ構造体の内容に応じて 変化します。
ワーク領域サイズの計算には、 criAtom_CalculateWorkSize_WASAPI 関数を使用してください。
備考:
criAtom_SetUserAllocator マクロを使用してアロケーターを登録済みの場合、 本関数にワーク領域を指定する必要はありません。
( work に NULL 、 work_size に 0 を指定することで、登録済みのアロケーター から必要なワーク領域サイズ分のメモリが動的に確保されます。)
引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。
注意:
本関数は内部的に以下の関数を実行します。
本関数を実行する場合、上記関数を実行しないでください。

本関数を実行後、必ず対になる criAtom_Finalize_WASAPI 関数を実行してください。
また、 criAtom_Finalize_WASAPI 関数を実行するまでは、本関数を再度実行しないでください。

本関数は下位レイヤ向けのAPIです。
AtomExレイヤの機能を利用する際には、本関数の代わりに criAtomEx_Initialize_WASAPI 関数をご利用ください。
参照:
CriAtomConfig_WASAPI, criAtom_Finalize_WASAPI, criAtom_SetUserAllocator, criAtom_CalculateWorkSize_WASAPI

void CRIAPI criAtom_Finalize_WASAPI ( void   ) 

ライブラリの終了

説明:
ライブラリを終了します。
注意:
本関数は内部的に以下の関数を実行します。
本関数を実行する場合、上記関数を実行しないでください。

criAtom_Initialize_WASAPI 関数実行前に本関数を実行することはできません。

本関数は下位レイヤ向けのAPIです。
AtomExレイヤの機能を利用する際には、本関数の代わりに criAtomEx_Finalize_WASAPI 関数をご利用ください。
参照:
criAtom_Initialize_WASAPI

CriBool CRIAPI criAtom_GetAudioClientMixFormat_WASAPI ( WAVEFORMATEXTENSIBLE *  format  ) 

ミキサフォーマットの取得

引数:
[out] format ミキサのフォーマット
戻り値:
CriBool ミキサのフォーマットが取得できたかどうか( CRI_TRUE = 成功、CRI_FALSE = 失敗)
説明:
共有モード時に使用されるミキサのフォーマットを取得します。
備考:
本関数は IAudioClient::GetMixFormat 関数のラッパーです。
本関数を実行すると、関数内で AudioClient を作成し、GetMixFormat 関数を実行します。
注意:
本関数はライブラリ初期化前にのみ使用可能です。

共有モードと排他モードとでは、使用できるフォーマットが異なります。
本関数で取得する WAVEFORMATEXTENSIBLE 構造体は IEEE float 形式のPCMデータフォーマットを返しますが、 このフォーマットは排他モードではほとんどの場合使用できません。

CriBool CRIAPI criAtom_GetAudioClientIsFormatSupported_WASAPI ( const WAVEFORMATEX *  format  ) 

指定したフォーマットが利用可能かどうかチェック

引数:
[in] format 使用するフォーマット
戻り値:
CriBool 指定されたフォーマットが利用可能かどうか( CRI_TRUE = 利用可能、CRI_FALSE = 利用不可能)
説明:
引数で指定したフォーマットが、排他モードで利用可能かどうかをチェックします。
備考:
本関数は IAudioClient::IsFormatSupported 関数のラッパーです。
本関数を実行すると、関数内で AudioClient を作成し、IsFormatSupported 関数を実行します。
注意:
本関数はライブラリ初期化前にのみ使用可能です。

一部のデバイス/パラメーターについて、本関数が成功するにもかかわらず、 WASAPI の初期化に失敗するケースが確認されています。
本関数が CRI_TRUE を返したにもかかわらず、ライブラリの初期化に失敗する場合には、 指定するフォーマットを変更するか、または共有モードをご使用ください。

void CRIAPI criAtom_SetAudioClientShareMode_WASAPI ( AUDCLNT_SHAREMODE  mode  ) 

共有方式の指定

引数:
[in] mode 使用するモード
説明:
WASAPIを共有モードで使用するか、排他モードで使用するかを指定します。

本関数を実行しない場合や、 AUDCLNT_SHAREMODE_SHARED を指定して実行した場合、 Atomライブラリは WASAPI を共有モードで初期化します。
AUDCLNT_SHAREMODE_EXCLUSIVE を指定して本関数を実行した場合、 Atomライブラリは WASAPI を排他モードで初期化します。
注意:
本関数はライブラリの初期化よりも先に実行しておく必要があります。

排他モードを使用する場合、本関数でのモード指定に加え、 criAtom_SetAudioClientFormat_WASAPI 関数によるフォーマットの指定が必要です。
参照:
criAtom_SetAudioClientFormat_WASAPI

void CRIAPI criAtom_SetAudioClientFormat_WASAPI ( const WAVEFORMATEX *  format  ) 

出力フォーマットの指定

説明:
引数:
[in] format 使用するフォーマット
説明:
排他モードで使用するフォーマットを指定します。
備考:
本関数に指定したフォーマットが、 IAudioClient::Initialize 関数に渡されます。
注意:
本関数はライブラリの初期化よりも先に実行しておく必要があります。

排他モードを使用する場合、本関数でのモード指定に加え、 criAtom_SetAudioClientShareMode_WASAPI 関数によるモード指定が必要です。
参照:
criAtom_SetAudioClientShareMode_WASAPI

void CRIAPI criAtom_SetAudioClientBufferDuration_WASAPI ( REFERENCE_TIME  ref_time  ) 

バッファリング時間の指定

引数:
[in] ref_time バッファリング時間
説明:
WASAPI 初期化時に指定するバッファリング時間を指定します。
Atomライブラリは、本関数で指定された時間分のデータを保持可能なサイズのサウンドバッファーを確保します。
備考:
本関数に指定した値が IAudioClient::Initialize 関数に渡されます。

ref_timeに0を指定した場合や、本関数を使用しない場合、 Atomライブラリは初期化時に指定されるサーバー処理周波数の値から、 適切なバッファリング時間を計算します。

PC環境ではハードウェア性能にばらつきがあるため、 ワースト性能のハードウェアに合わせてデフォルトのバッファリング量が多めに設定されています。
(デフォルト状態では4V分のバッファーを持っています。)
注意:
本関数はライブラリの初期化よりも先に実行しておく必要があります。

バッファリング時間を小さくしすぎると、音途切れ等の問題が発生します。

PC環境ではハードウェアに依存して必要なバッファリング量が異なるため、 本関数を使用した場合、テスト環境でうまく動作していても、 ユーザの環境によっては音途切れが発生する可能性があります。
そのため、バッファリング量を変更する場合には、 ユーザが設定値を変更できる仕組み(オプション画面等)を提供することもご検討ください。

IAudioClient* CRIAPI criAtom_GetAudioClient_WASAPI ( void   ) 

AudioClientの取得

戻り値:
IAudioClient AudioClient
説明:
Atomライブラリ内で作成されたAudioClientを取得します。
備考:
サウンドデバイスが搭載されていないPCで本関数を実行した場合、 本関数はNULLを返します。
注意:
本関数を実行する前に、ライブラリを初期化する必要があります。

CriBool CRIAPI criAtom_IsDeviceInvalidated_WASAPI ( void   ) 

デバイスが無効化されたかどうかのチェック

戻り値:
CriBool デバイスが無効化されたかどうか(CRI_TRUE = 無効化された、CRI_FALSE = 正常に動作中)
説明:
サウンドデバイスが無効化されたかどうかを返します。
備考:
本関数がCRI_TRUEを返すのは、アプリケーション実行中にサウンドデバイスを無効化した場合のみです。
元々サウンドデバイスが搭載されていないPCで本関数を実行した場合、本関数はCRI_FALSEを返します。
(サウンドデバイスの有無は別途 criAtom_GetAudioClient_WASAPI 関数でチェックする必要があります。)
参照:
criAtom_GetAudioClient_WASAPI

void CRIAPI criAtom_SetDeviceId_WASAPI ( CriAtomSoundRendererType  type,
LPCWSTR  device_id 
)

サウンドデバイスの指定

引数:
[in] type サウンドレンダラタイプ
[in] device_id デバイスID
説明:
サウンドレンダラタイプとサウンドデバイスの紐づけを行います。

本関数でサウンドレンダラに対してデバイスIDを設定すると、 当該サウンドレンダラを指定して出力した音声は、 全て指定したIDに合致するサウンドデバイスから出力されます。
type には、以下の値が指定可能です。
  • CRIATOM_SOUND_RENDERER_HW1(CRIATOM_SOUND_RENDERER_NATIVEと同じ値)
  • CRIATOM_SOUND_RENDERER_HW2
  • CRIATOM_SOUND_RENDERER_HW3
  • CRIATOM_SOUND_RENDERER_HW4
第2引数(device_id)にNULLまたは長さ0の文字列を指定した場合、 当該サウンドレンダラとデバイスIDの紐づけが解除されます。
(既定のデバイスから音声を出力するよう、動作が変更されます。)
備考:
サウンドデバイスのIDは IMMDevice::GetId で取得する必要があります。
指定されたIDに一致するサウンドデバイスが見つからない場合、 当該デバイスを指定して再生された音声は、既定のデバイスから出力されます。

CriSint32 CRIAPI criAtom_EnumAudioEndpoints_WASAPI ( CriAtomAudioEndpointCbFunc_WASAPI  callback,
void *  object 
)

オーディオエンドポイントの列挙

引数:
[in] callback オーディオエンドポイントコールバック関数
[in] object ユーザ指定オブジェクト
戻り値:
CriSint32 列挙されたACBハンドルの数
説明:
オーディオエンドポイントを列挙します。

本関数を実行すると、第 1 引数( callback ) でセットされたコールバック関数がオーディオエンドポイント数分だけ呼び出されます。
コールバック関数には、IMMDeviceインスタンスが引数として渡されます。
備考:
第 2 引数( object )にセットした値は、コールバック関数の引数として渡されます。
コールバック関数のその他の引数については、 別途 CriAtomAudioEndpointCbFunc_WASAPI の説明をご参照ください。

戻り値は列挙されたオーディオエンドポイントの数(登録したコールバック関数が呼び出された回数)です。
オーディオエンドポイントが存在しない場合、本関数は 0 を返します。
エラーが発生した際には -1 を返します。
注意:
IMMDeviceインスタンスをコールバック関数内で破棄してはいけません。
参照:
CriAtomAudioEndpointCbFunc_WASAPI

void CRIAPI criAtom_SetDeviceUpdateCallback_WASAPI ( CriAtomDeviceUpdateCbFunc_WASAPI  callback,
void *  object 
)

デバイス更新通知の登録

引数:
[in] callback デバイス更新通知コールバック関数
[in] object ユーザ指定オブジェクト
説明:
デバイスの更新通知を受け取るためのコールバックを設定します。

本関数を実行すると、デバイスが更新された際、第 1 引数( callback ) でセットされたコールバック関数が呼び出されます。
備考:
第 2 引数( object )にセットした値は、コールバック関数の引数として渡されます。
参照:
CriAtomAudioEndpointCbFunc_WASAPI

CriSint32 CRIAPI criAtomEx_CalculateWorkSize_WASAPI ( const CriAtomExConfig_WASAPI config  ) 

ライブラリ初期化用ワーク領域サイズの計算

引数:
[in] config 初期化用コンフィグ構造体
戻り値:
CriSint32 ワーク領域サイズ
説明:
ライブラリを使用するために必要な、ワーク領域のサイズを取得します。
備考:
ライブラリが必要とするワーク領域のサイズは、ライブラリ初期化用コンフィグ 構造体( CriAtomExConfig_WASAPI )の内容によって変化します。

引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。
注意:
CriAtomExConfig_WASAPI 構造体のacf_infoメンバに値を設定している場合、本関数は失敗し-1を返します。
初期化処理内でACFデータの登録を行う場合は、本関数値を使用したメモリ確保ではなくADX2システムによる メモリアロケーターを使用したメモリ確保処理が必要になります。
参照:
CriAtomExConfig_WASAPI, criAtomEx_Initialize_WASAPI

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

ライブラリの初期化

引数:
[in] config 初期化用コンフィグ構造体
[in] work ワーク領域
[in] work_size ワーク領域サイズ
説明:
ライブラリを初期化します。
ライブラリの機能を利用するには、必ずこの関数を実行する必要があります。
(ライブラリの機能は、本関数を実行後、 criAtomEx_Finalize_WASAPI 関数を実行するまでの間、 利用可能です。)

ライブラリを初期化する際には、ライブラリが内部で利用するためのメモリ領域(ワーク領域) を確保する必要があります。
ライブラリが必要とするワーク領域のサイズは、初期化用コンフィグ構造体の内容に応じて 変化します。
ワーク領域サイズの計算には、 criAtomEx_CalculateWorkSize_WASAPI 関数を使用してください。
備考:
criAtomEx_SetUserAllocator マクロを使用してアロケーターを登録済みの場合、 本関数にワーク領域を指定する必要はありません。
( work に NULL 、 work_size に 0 を指定することで、登録済みのアロケーター から必要なワーク領域サイズ分のメモリが動的に確保されます。)
引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。
注意:
本関数は内部的に以下の関数を実行します。
本関数を実行する場合、上記関数を実行しないでください。

本関数を実行後、必ず対になる criAtomEx_Finalize_WASAPI 関数を実行してください。
また、 criAtomEx_Finalize_WASAPI 関数を実行するまでは、本関数を再度実行しないでください。
参照:
CriAtomExConfig_WASAPI, criAtomEx_Finalize_WASAPI, criAtomEx_SetUserAllocator, criAtomEx_CalculateWorkSize_WASAPI

void CRIAPI criAtomEx_Finalize_WASAPI ( void   ) 

ライブラリの終了

説明:
ライブラリを終了します。
注意:
本関数は内部的に以下の関数を実行します。
本関数を実行する場合、上記関数を実行しないでください。

criAtomEx_Initialize_WASAPI 関数実行前に本関数を実行することはできません。
参照:
criAtomEx_Initialize_WASAPI


CRI Middleware logo Copyright (c) 2006-2018 CRI Middleware Co., Ltd.