Metode IAudioCaptureClient::GetBuffer (audioclient.h)
Mengambil pointer ke paket data berikutnya yang tersedia di buffer titik akhir pengambilan.
Sintaks
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Parameter
[out] ppData
Penunjuk ke variabel pointer tempat metode menulis alamat awal paket data berikutnya yang tersedia untuk dibaca klien.
[out] pNumFramesToRead
Penunjuk ke variabel UINT32 tempat metode menulis jumlah bingkai (jumlah bingkai audio yang tersedia dalam paket data). Klien harus membaca seluruh paket data atau tidak sama sekali.
[out] pdwFlags
Arahkan ke variabel DWORD tempat metode menulis bendera status buffer. Metode ini menulis kombinasi 0 atau bitwise-OR dari satu atau beberapa nilai enumerasi _AUDCLNT_BUFFERFLAGS berikut:
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
Dalam rilis OS Windows 7 dan yang lebih baru, bendera ini dapat digunakan untuk deteksi kesalahan. Untuk memulai aliran pengambilan, aplikasi klien harus memanggil IAudioClient::Start diikuti dengan panggilan ke GetBuffer dalam perulangan untuk membaca paket data hingga semua paket yang tersedia di buffer titik akhir telah dibaca. GetBuffer mengatur bendera AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY untuk menunjukkan kesalahan dalam buffer yang ditunjukkan oleh ppData.
[out] pu64DevicePosition
Arahkan ke variabel UINT64 tempat metode menulis posisi perangkat bingkai audio pertama dalam paket data. Posisi perangkat dinyatakan sebagai jumlah bingkai audio dari awal aliran. Parameter ini bisa NULL jika klien tidak memerlukan posisi perangkat. Untuk informasi selengkapnya, lihat Keterangan.
[out] pu64QPCPosition
Penunjuk ke variabel UINT64 tempat metode menulis nilai penghitung kinerja pada saat perangkat titik akhir audio merekam posisi perangkat bingkai audio pertama dalam paket data. Metode ini mengonversi nilai penghitung menjadi 100 unit nanodetik sebelum menulisnya ke *pu64QPCPosition. Parameter ini bisa NULL jika klien tidak memerlukan nilai penghitung kinerja. Untuk informasi selengkapnya, lihat Keterangan.
Nilai kembali
Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, nilai yang diperlihatkan dalam tabel berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Panggilan berhasil dan *pNumFramesToRead bukan nol, menunjukkan bahwa paket siap dibaca. |
|
Panggilan berhasil dan *pNumFramesToRead adalah 0, menunjukkan bahwa tidak ada data tangkapan yang tersedia untuk dibaca. |
|
Windows 7 dan yang lebih baru: GetBuffer gagal mengambil buffer data dan *ppData menunjuk ke NULL. Untuk informasi selengkapnya, lihat Keterangan. |
|
Panggilan IAudioCaptureClient::GetBuffer sebelumnya masih berlaku. |
|
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. |
|
Buffer tidak dapat diakses karena reset aliran sedang berlangsung. |
|
Layanan audio Windows tidak berjalan. |
|
Parameter ppData, pNumFramesToRead, atau pdwFlags adalah NULL. |
Keterangan
Metode ini mengambil paket data berikutnya dari buffer titik akhir pengambilan. Pada waktu tertentu, buffer mungkin berisi nol, satu, atau beberapa paket yang siap dibaca. Biasanya, utas pemrosesan buffer yang membaca data dari buffer titik akhir tangkapan membaca semua paket yang tersedia setiap kali utas dijalankan.
Selama pemrosesan aliran pengambilan audio, aplikasi klien secara bergantian memanggil GetBuffer dan metode IAudioCaptureClient::ReleaseBuffer . Klien dapat membaca tidak lebih dari satu paket data dengan setiap panggilan GetBuffer . Mengikuti setiap panggilan GetBuffer , klien harus memanggil ReleaseBuffer untuk merilis paket sebelum klien dapat memanggil GetBuffer lagi untuk mendapatkan paket berikutnya.
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.
Selama setiap panggilan GetBuffer , penelepon harus mendapatkan seluruh paket atau tidak sama sekali. Sebelum membaca paket, penelepon dapat memeriksa ukuran paket (tersedia melalui parameter pNumFramesToRead ) untuk memastikan bahwa ia memiliki cukup ruang untuk menyimpan seluruh paket.
Selama setiap panggilan ReleaseBuffer , pemanggil melaporkan jumlah bingkai audio yang dibacanya dari buffer. Angka ini harus berukuran paket (bukan nol) atau 0. Jika nomornya 0, maka panggilan GetBuffer berikutnya akan menyajikan pemanggil dengan paket yang sama seperti dalam panggilan GetBuffer sebelumnya.
Mengikuti setiap panggilan GetBuffer , data dalam paket tetap valid hingga panggilan ReleaseBuffer berikutnya merilis buffer.
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.
Metode ini menghasilkan posisi perangkat dan penghitung kinerja melalui parameter output pu64DevicePosition dan pu64QPCPosition . Nilai-nilai ini menyediakan stempel waktu untuk bingkai audio pertama dalam paket data. Melalui parameter output pdwFlags , metode menunjukkan apakah posisi perangkat yang dilaporkan valid.
Posisi perangkat yang ditulis metode ke *pu64DevicePosition adalah posisi relatif aliran dari bingkai audio yang saat ini diputar melalui speaker (untuk aliran penyajian) atau direkam melalui mikrofon (untuk aliran pengambilan). Posisi dinyatakan sebagai jumlah bingkai dari awal aliran. Ukuran bingkai dalam aliran audio ditentukan oleh anggota nBlockAlign dari struktur WAVEFORMATEX (atau WAVEFORMATEXTENSIBLE) yang menentukan format aliran. Ukuran, dalam byte, dari bingkai audio sama dengan jumlah saluran dalam aliran yang dikalikan dengan ukuran sampel per saluran. Misalnya, untuk aliran stereo (2 saluran) dengan sampel 16-bit, ukuran bingkai adalah empat byte.
Nilai penghitung kinerja yang ditulis GetBuffer ke *pu64QPCPosition bukanlah nilai penghitung mentah yang diperoleh dari fungsi QueryPerformanceCounter . Jika t adalah nilai penghitung mentah, dan jika f adalah frekuensi yang diperoleh dari fungsi QueryPerformanceFrequency , GetBuffer menghitung nilai penghitung kinerja sebagai berikut:
*pu64QPCPosition = 10.000.000.T/F
Hasilnya dinyatakan dalam 100 unit nanodetik. Untuk informasi selengkapnya tentang QueryPerformanceCounter dan QueryPerformanceFrequency, lihat dokumentasi Windows SDK.
Jika saat ini tidak ada paket baru yang tersedia, metode menetapkan *pNumFramesToRead = 0 dan mengembalikan kode status AUDCLNT_S_BUFFER_EMPTY. Dalam hal ini, metode tidak menulis ke variabel yang ditunjukkan oleh parameter ppData, pu64DevicePosition, dan pu64QPCPosition .
Klien harus menghindari penundaan berlebihan antara panggilan GetBuffer yang memperoleh paket dan panggilan ReleaseBuffer yang merilis paket. Implementasi mesin audio mengasumsikan bahwa panggilan GetBuffer dan panggilan ReleaseBuffer yang sesuai terjadi dalam periode pemrosesan buffer yang sama. Klien yang menunda merilis paket untuk lebih dari satu periode berisiko kehilangan data sampel.
Di Windows 7 dan yang lebih baru, 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 Menangkap Stream.
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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk