Metode IXAudio2::CreateSourceVoice (xaudio2.h)

Artikel
08/28/2023

Membuat dan mengonfigurasi suara sumber.

Sintaks

HRESULT CreateSourceVoice(
  [out]          IXAudio2SourceVoice        **ppSourceVoice,
  [in]           const WAVEFORMATEX         *pSourceFormat,
  [in]           UINT32                     Flags,
  [in]           float                      MaxFrequencyRatio,
  [in, optional] IXAudio2VoiceCallback      *pCallback,
  [in, out]      const XAUDIO2_VOICE_SENDS  *pSendList,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

Parameter

[out] ppSourceVoice

Jika berhasil, mengembalikan pointer ke objek IXAudio2SourceVoice baru.

[in] pSourceFormat

Penunjuk ke salah satu struktur dalam tabel di bawah ini. Struktur ini berisi format yang diharapkan untuk semua buffer audio yang dikirimkan ke suara sumber. XAudio2 mendukung jenis suara PCM dan ADPCM.

Format tag	Struktur format gelombang	Ukuran Halaman (dalam Byte)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
-atau-	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32-bit]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2 mendukung format PCM berikut.

PCM bilangan bulat 8-bit (tidak ditandatangani)
PCM bilangan bulat 16-bit (format optimal untuk XAudio2)
PCM bilangan bulat 20-bit (baik dalam kontainer 24 atau 32 bit)
PCM bilangan bulat 24-bit (baik dalam kontainer 24 atau 32 bit)
PCM bilangan bulat 32-bit
PCM float 32-bit (format pilihan setelah bilangan bulat 16-bit)

Jumlah saluran dalam suara sumber harus kurang dari atau sama dengan XAUDIO2_MAX_AUDIO_CHANNELS. Laju sampel suara sumber harus antara XAUDIO2_MIN_SAMPLE_RATE dan XAUDIO2_MAX_SAMPLE_RATE.

Catatan Format data PCM seperti PCMWAVEFORMAT dan ADPCMWAVEFORMAT yang memerlukan lebih banyak informasi daripada yang disediakan oleh WAVEFORMATEX memiliki struktur WAVEFORMATEX sebagai anggota pertama dalam struktur format mereka. Saat Anda membuat suara sumber dengan salah satu format tersebut, transmisikan struktur format sebagai struktur WAVEFORMATEX dan gunakan sebagai nilai untuk pSourceFormat.

[in] Flags

Bendera yang menentukan perilaku suara sumber. Bendera bisa 0 atau kombinasi dari satu atau beberapa hal berikut:

Nilai	Deskripsi
XAUDIO2_VOICE_NOPITCH	Tidak ada kontrol nada yang tersedia pada suara.
XAUDIO2_VOICE_NOSRC	Tidak ada konversi laju sampel yang tersedia pada suara. Output suara harus memiliki laju sampel yang sama. Catatan Bendera XAUDIO2_VOICE_NOSRC menyebabkan suara berperilaku seolah-olah bendera XAUDIO2_VOICE_NOPITCH juga ditentukan.
XAUDIO2_VOICE_USEFILTER	Efek filter harus tersedia pada suara ini.

Catatan Bendera XAUDIO2_VOICE_MUSIC tidak didukung pada Windows.

[in] MaxFrequencyRatio

Rasio frekuensi tertinggi yang diperbolehkan yang dapat diatur pada suara ini. Nilai untuk argumen ini harus antara XAUDIO2_MIN_FREQ_RATIO dan XAUDIO2_MAX_FREQ_RATIO. Panggilan berikutnya ke IXAudio2SourceVoice::SetFrequencyRatio dijepit antara XAUDIO2_MIN_FREQ_RATIO dan MaxFrequencyRatio. Nilai maksimum untuk argumen ini didefinisikan sebagai XAUDIO2_MAX_FREQ_RATIO, yang memungkinkan nada dinaikkan hingga 10 oktaf.

Jika MaxFrequencyRatio kurang dari 1.0, suara akan menggunakan rasio tersebut segera setelah dibuat (bukan default 1,0).

Xbox 360
Untuk suara XMA, ada satu batasan lagi pada argumen MaxFrequencyRatio dan laju sampel suara. Produk dari kedua angka ini tidak boleh melebihi XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO untuk suara satu saluran atau XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL untuk suara dengan jumlah saluran lainnya. Jika nilai yang ditentukan untuk MaxFrequencyRatio terlalu tinggi untuk format yang ditentukan, panggilan ke CreateSourceVoice gagal dan menghasilkan pesan debug.

Xbox 360

Untuk suara XMA, ada satu batasan lagi pada argumen MaxFrequencyRatio dan laju sampel suara. Produk dari kedua angka ini tidak boleh melebihi XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO untuk suara satu saluran atau XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL untuk suara dengan jumlah saluran lainnya. Jika nilai yang ditentukan untuk MaxFrequencyRatio terlalu tinggi untuk format yang ditentukan, panggilan ke CreateSourceVoice gagal dan menghasilkan pesan debug.

Catatan Anda dapat menggunakan nilai MaxFrequencyRatio serendah mungkin untuk mengurangi penggunaan memori XAudio2.

[in, optional] pCallback

Arahkan ke antarmuka panggilan balik yang disediakan klien, IXAudio2VoiceCallback.

[in, out] pSendList

Arahkan ke daftar struktur XAUDIO2_VOICE_SENDS yang menjelaskan kumpulan suara tujuan untuk suara sumber. Jika pSendList adalah NULL, daftar kirim default ke satu output ke suara master pertama yang dibuat.

[in, optional] pEffectChain

Arahkan ke daftar struktur XAUDIO2_EFFECT_CHAIN yang menjelaskan rantai efek untuk digunakan dalam suara sumber.

Mengembalikan nilai

Mengembalikan S_OK jika berhasil; jika tidak, kode kesalahan.

Lihat Kode Kesalahan XAudio2 untuk deskripsi kode kesalahan khusus XAudio2.

Keterangan

Suara sumber membaca data audio dari klien. Mereka memproses data dan mengirimkannya ke grafik pemrosesan XAudio2.

Suara sumber menyertakan konversi laju sampel laju variabel, untuk mengonversi data dari laju sampel format sumber ke tingkat output yang diperlukan untuk daftar pengiriman suara. Jika Anda menggunakan daftar pengiriman NULL, laju sampel target akan menjadi laju sampel input suara master. Jika Anda memberikan satu suara di pSendList, laju sampel input suara tersebut adalah laju target. Jika Anda menyediakan beberapa suara di pSendList, semua suara output suara sumber harus berjalan pada laju sampel input yang sama.

Anda tidak dapat membuat suara sumber atau submix apa pun hingga suara penguasaan ada, dan Anda tidak dapat menghancurkan suara master jika ada suara sumber atau submix yang masih ada.

Suara sumber selalu diproses sebelum submix atau suara yang menguasai. Ini berarti Anda tidak memerlukan parameter ProcessingStage untuk mengontrol urutan pemrosesan.

Saat pertama kali dibuat, suara sumber berada dalam status berhenti.

XAudio2 menggunakan pengumpul memori internal untuk suara dengan format yang sama. Ini berarti alokasi memori untuk suara akan terjadi lebih jarang karena lebih banyak suara dibuat dan kemudian dihancurkan. Untuk meminimalkan alokasi just-in-time, judul dapat membuat jumlah suara maksimum yang diantisipasi yang diperlukan di depan, lalu menghapusnya seperlunya. Suara kemudian akan digunakan kembali dari kumpulan XAudio2. Kumpulan memori terkait dengan instans mesin XAudio2. Anda dapat mengklaim kembali semua memori yang digunakan oleh instans mesin XAudio2 dengan menghancurkan objek XAudio2 dan membuatnya kembali seperlunya (memaksa kumpulan memori untuk tumbuh melalui pra-alokasi harus diterapkan kembali sesuai kebutuhan).

Tidak valid untuk memanggil CreateSourceVoice dari dalam panggilan balik (yaitu, IXAudio2EngineCallback atau IXAudio2VoiceCallback). Jika Anda memanggil CreateSourceVoice dalam panggilan balik, panggilan balik 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 CreateSourceVoice berhasil diselesaikan, dan dapat dihapus segera setelah CreateSourceVoice dipanggil.