Metode IAudioRenderClient::GetBuffer (audioclient.h)

Artikel
03/14/2023

Mengambil penunjuk ke ruang berikutnya yang tersedia di buffer titik akhir penyajian tempat pemanggil dapat menulis paket data.

Sintaks

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

Parameter

[in] NumFramesRequested

Jumlah bingkai audio dalam paket data yang di rencanakan pemanggil untuk menulis ke ruang yang diminta di buffer. Jika panggilan berhasil, ukuran area buffer yang ditunjukkan oleh *ppData cocok dengan ukuran yang ditentukan dalam NumFramesRequested.

[out] ppData

Penunjuk ke variabel penunjuk tempat metode menulis alamat awal area buffer tempat pemanggil akan menulis paket data.

Nilai kembali

Jika metode berhasil, metode akan mengembalikan S_OK. Jika gagal, kemungkinan kode pengembalian menyertakan, tetapi tidak terbatas pada, nilai yang diperlihatkan dalam tabel berikut.

Menampilkan kode	Deskripsi
AUDCLNT_E_BUFFER_ERROR	GetBuffer gagal mengambil buffer data dan *ppData menunjuk ke NULL. Untuk informasi selengkapnya, lihat Keterangan.
AUDCLNT_E_BUFFER_TOO_LARGE	Nilai NumFramesRequested melebihi ruang buffer yang tersedia (ukuran buffer dikurangi ukuran padding).
AUDCLNT_E_BUFFER_SIZE_ERROR	Streaming adalah mode eksklusif dan menggunakan buffering berbasis peristiwa, tetapi klien mencoba untuk mendapatkan paket yang bukan ukuran buffer.
AUDCLNT_E_OUT_OF_ORDER	Panggilan IAudioRenderClient::GetBuffer sebelumnya masih berlaku.
AUDCLNT_E_DEVICE_INVALIDATED	Perangkat titik akhir audio telah dicabut, atau perangkat keras audio atau sumber daya perangkat keras terkait telah dikonfigurasi ulang, dinonaktifkan, dihapus, atau dibuat tidak tersedia untuk digunakan.
AUDCLNT_E_BUFFER_OPERATION_PENDING	Buffer tidak dapat diakses karena reset aliran sedang berlangsung.
AUDCLNT_E_SERVICE_NOT_RUNNING	Layanan audio Windows tidak berjalan.
E_POINTER	Parameter ppData adalah NULL.

Keterangan

Pemanggil dapat meminta ukuran paket yang kurang dari atau sama dengan jumlah ruang yang tersedia di buffer (kecuali dalam kasus aliran mode eksklusif yang menggunakan buffering berbasis peristiwa; untuk informasi selengkapnya, lihat IAudioClient::Initialize). Ruang yang tersedia hanyalah ukuran buffer dikurangi jumlah data dalam buffer yang sudah diantrekan untuk dimainkan. Jika pemanggil menentukan nilai NumFramesRequested yang melebihi ruang yang tersedia di buffer, panggilan gagal dan mengembalikan kode kesalahan AUDCLNT_E_BUFFER_TOO_LARGE.

Klien bertanggung jawab untuk menulis sejumlah data yang cukup ke buffer untuk mencegah gangguan terjadi di aliran audio. Untuk informasi selengkapnya tentang persyaratan buffering, lihat IAudioClient::Initialize.

Setelah mendapatkan paket data dengan memanggil GetBuffer, klien mengisi paket dengan merender data dan mengeluarkan paket ke mesin audio dengan memanggil metode IAudioRenderClient::ReleaseBuffer .

Klien harus memanggil ReleaseBuffer setelah panggilan GetBuffer yang berhasil mendapatkan paket dengan ukuran apa pun selain 0. Klien memiliki opsi untuk memanggil atau tidak memanggil ReleaseBuffer untuk merilis paket ukuran 0.

Untuk ukuran paket bukan nol, klien harus melakukan panggilan alternatif ke GetBuffer dan ReleaseBuffer. Setiap panggilan GetBuffer harus diikuti oleh panggilan ReleaseBuffer yang sesuai. Setelah klien memanggil GetBuffer untuk memperoleh paket data, klien tidak dapat memperoleh paket data berikutnya sampai disebut ReleaseBuffer untuk merilis paket sebelumnya. Dua atau lebih panggilan berturut-turut baik ke GetBuffer atau ke ReleaseBuffer tidak diizinkan dan akan gagal dengan kode kesalahan AUDCLNT_E_OUT_OF_ORDER.

Untuk memastikan urutan panggilan yang benar, panggilan GetBuffer dan panggilan ReleaseBuffer yang sesuai harus terjadi di utas yang sama.

Ukuran bingkai audio ditentukan oleh anggota nBlockAlign dari struktur WAVEFORMATEX yang diperoleh klien dengan memanggil metode IAudioClient::GetMixFormat .

Jika penelepon mengatur NumFramesRequested = 0, metode mengembalikan kode status S_OK tetapi tidak menulis ke variabel yang ditunjuk parameter ppData .

Klien harus menghindari penundaan berlebihan antara panggilan GetBuffer yang memperoleh buffer dan panggilan ReleaseBuffer yang merilis buffer. Implementasi mesin audio mengasumsikan bahwa panggilan GetBuffer dan panggilan ReleaseBuffer yang sesuai terjadi dalam periode pemrosesan buffer yang sama. Klien yang menunda merilis buffer untuk lebih dari satu periode berisiko kehilangan data sampel.

Di Windows 7, GetBuffer dapat mengembalikan kode kesalahan AUDCLNT_E_BUFFER_ERROR untuk klien audio yang menggunakan buffer titik akhir dalam mode eksklusif. Kesalahan ini menunjukkan bahwa buffer data tidak diambil karena paket data tidak tersedia (*ppData menerima NULL).

Jika GetBuffer mengembalikan AUDCLNT_E_BUFFER_ERROR, utas yang mengkonsumsi sampel audio harus menunggu pass pemrosesan berikutnya. Klien mungkin mendapat manfaat dari menyimpan hitungan panggilan GetBuffer yang gagal. Jika GetBuffer mengembalikan kesalahan ini berulang kali, klien dapat memulai perulangan pemrosesan baru setelah mematikan klien saat ini dengan memanggil IAudioClient::Stop, IAudioClient::Reset, dan merilis klien audio.

Contoh

Untuk contoh kode yang memanggil metode GetBuffer , lihat topik berikut:

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	audioclient.h