Metode IXAudio2Voice::SetEffectParameters (xaudio2.h)

Artikel
08/28/2023

Mengatur parameter untuk efek tertentu dalam rantai efek suara.

Sintaks

\\HRESULT SetEffectParameters(
  [in] UINT32     EffectIndex,
  [in] const void *pParameters,
  [in] UINT32     ParametersByteSize,
  [in] UINT32     OperationSet
);

Parameter

[in] EffectIndex

Indeks berbasis nol efek dalam rantai efek suara.

[in] pParameters

Mengembalikan nilai saat ini dari parameter khusus efek.

[in] ParametersByteSize

Ukuran array pParameters dalam byte.

[in] OperationSet

Mengidentifikasi panggilan ini sebagai bagian dari batch yang ditangguhkan. Lihat gambaran umum XAudio2 Operation Sets untuk informasi selengkapnya.

Nilai kembali

Mengembalikan S_OK jika berhasil; jika tidak, kode kesalahan. Lihat Kode Kesalahan XAudio2 untuk deskripsi kode kesalahan.

Gagal dengan E_NOTIMPL jika efek tidak mendukung antarmuka kontrol parameter generik.

Keterangan

Efek spesifik yang digunakan menentukan ukuran dan format buffer pParameters yang valid. Panggilan akan gagal jika pParameters tidak valid atau jika ParametersByteSize tidak persis ukuran yang diharapkan efek. Klien harus berhati-hati untuk mengarahkan panggilan SetEffectParameters ke efek yang tepat. Jika panggilan ini diarahkan ke efek berbeda yang kebetulan menerima ukuran blok parameter yang sama, parameter akan ditafsirkan secara berbeda. Ini dapat menyebabkan hasil yang tidak terduga.

Memori yang ditujukan oleh pParameterstidak boleh segera dibebaskan, karena XAudio2 perlu merujuknya nanti ketika parameter benar-benar diterapkan pada efeknya. Ini terjadi selama pass pemrosesan audio berikutnya jika argumen OperationSetXAUDIO2_COMMIT_NOW. Jika tidak, parameter diterapkan ke efek nanti, selama pass pemrosesan pertama setelah fungsi IXAudio2::CommitChanges dipanggil dengan argumen OperationSet yang sama.

SetEffectParameters langsung berlaku ketika dipanggil dari panggilan balik XAudio2 dengan OperationSetXAUDIO2_COMMIT_NOW.

CatatanIXAudio2Voice::GetEffectParameters selalu mengembalikan parameter aktual efek saat ini. Namun, ini mungkin tidak cocok dengan parameter yang ditetapkan oleh panggilan terbaru ke IXAudio2Voice::SetEffectParameters. Parameter aktual hanya diubah saat mesin audio berjalan setelah panggilan IXAudio2Voice::SetEffectParameters (atau setelah panggilan IXAudio2::CommitChanges yang sesuai, jika IXAudio2Voice::SetEffectParameters dipanggil dengan ID operasi yang ditangguhkan).