IXAudio2::CreateMasteringVoice method (xaudio2.h)

Artikel
03/08/2023

Membuat dan mengonfigurasi suara mastering.

Sintaks

HRESULT CreateMasteringVoice(
  [out]          IXAudio2MasteringVoice     **ppMasteringVoice,
  [in]           UINT32                     InputChannels,
  [in]           UINT32                     InputSampleRate,
  [in]           UINT32                     Flags,
  [in]           LPCWSTR                    szDeviceId,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain,
  [in, optional] AUDIO_STREAM_CATEGORY      StreamCategory
);

Parameter

[out] ppMasteringVoice

Jika berhasil, mengembalikan penunjuk ke objek IXAudio2MasteringVoice baru.

[in] InputChannels

Jumlah saluran yang diharapkan suara master dalam audio inputnya. InputChannels harus kurang dari atau sama dengan XAUDIO2_MAX_AUDIO_CHANNELS.

Anda dapat mengatur InputChannels ke XAUDIO2_DEFAULT_CHANNELS, yang menyebabkan XAudio2 mencoba mendeteksi penyiapan konfigurasi speaker sistem.

[in] InputSampleRate

Laju sampel data audio input suara master. Tarif ini harus berupa kelipatan XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate harus antara XAUDIO2_MIN_SAMPLE_RATE dan XAUDIO2_MAX_SAMPLE_RATE.

Anda dapat mengatur InputSampleRate ke XAUDIO2_DEFAULT_SAMPLERATE, dengan default ditentukan oleh platform saat ini.

Windows XP default ke 44100.

Windows Vista dan Windows 7 default ke pengaturan yang ditentukan dalam Panel Kontrol Suara. Default untuk pengaturan ini adalah 44100 (atau 48000 jika diperlukan oleh driver).

Bendera

[in] Flags

Bendera yang menentukan perilaku suara master. Ini bisa 0 atau XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Pengidentifikasi perangkat untuk menerima audio output. Menentukan nilai default NULL menyebabkan XAudio2 memilih perangkat audio default global. Pada Windows 10 atau yang lebih baru, NULL juga akan ikut serta ke klien virtual WASAPI kecuali XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT diteruskan dalam Bendera.

[in, optional] pEffectChain

Arahkan ke struktur XAUDIO2_EFFECT_CHAIN yang menjelaskan rantai efek untuk digunakan dalam suara mastering, atau NULL untuk tidak menggunakan efek apa pun.

[in, optional] StreamCategory

Kategori aliran audio yang akan digunakan untuk suara mastering ini.

Mengembalikan nilai

Mengembalikan S_OK jika berhasil; jika tidak, kode kesalahan. Mengembalikan ERROR_NOT_FOUND jika tidak ada perangkat audio default dan NULL diteruskan sebagai parameter szDeviceId.

Lihat Kode Kesalahan XAudio2 untuk deskripsi kode kesalahan spesifik XAudio2.

Keterangan

Suara master menerima output dari satu atau beberapa suara sumber atau submix. Mereka memproses data, dan mengirimkannya ke perangkat output audio.

Biasanya, Anda harus membuat suara master dengan laju sampel input yang akan digunakan oleh sebagian besar konten audio judul. Suara mastering melakukan konversi laju sampel dari laju sampel input ini ke tingkat output perangkat aktual.

Anda tidak dapat membuat suara sumber atau submix hingga ada suara yang menguasai. Anda tidak dapat menghancurkan suara master jika ada suara sumber atau submix yang masih ada.

Suara master selalu diproses setelah semua suara sumber dan submix. Ini berarti Anda tidak perlu menentukan parameter ProcessingStage untuk mengontrol urutan pemrosesan.

XAudio2 hanya memungkinkan satu suara penguasaan ada sekaligus. Jika Anda mencoba membuat lebih dari satu suara, XAUDIO2_E_INVALID_CALL dikembalikan. Jika suara mastering tambahan diperlukan, misalnya untuk perangkat output dengan set kategori audio yang berbeda, Anda harus membuat instans XAudio2 tambahan.

Saat pertama kali dibuat, suara master berada dalam status dimulai.

Tidak valid untuk memanggil CreateMasteringVoice dari dalam panggilan balik (yaitu, IXAudio2EngineCallback atau IXAudio2VoiceCallback). Jika Anda memanggil CreateMasteringVoice dalam panggilan balik, itu akan mengembalikan XAUDIO2_E_INVALID_CALL.

XAUDIO2_EFFECT_CHAIN yang diteruskan sebagai argumen pEffectChain dan informasi XAUDIO2_EFFECT_DESCRIPTOR apa pun yang terkandung di dalamnya tidak lagi diperlukan setelah CreateMasteringVoice berhasil diselesaikan, dan dapat dihapus segera setelah CreateMasteringVoice dipanggil.

Perhatikan bahwa SDK DirectX XAUDIO2 versi CreateMasteringVoice mengambil argumen DeviceIndex alih-alih argumen szDeviceId dan StreamCategory. Ini mencerminkan perubahan yang diperlukan untuk model enumerasi perangkat Windows standar.