IAudioClock::Metode GetPosition (audioclient.h)

Artikel
03/14/2023

Metode GetPosition mendapatkan posisi perangkat saat ini.

Sintaks

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

Parameter

[out] pu64Position

Arahkan ke variabel UINT64 tempat metode menulis posisi perangkat. Posisi perangkat adalah offset dari awal aliran ke posisi saat ini di aliran. Namun, unit di mana offset ini dinyatakan tidak terdefinisi—nilai posisi perangkat hanya memiliki arti dalam kaitannya dengan frekuensi yang dilaporkan oleh metode IAudioClock::GetFrequency . Untuk informasi selengkapnya, lihat Keterangan.

[out] pu64QPCPosition

Arahkan ke variabel UINT64 tempat metode menulis nilai penghitung kinerja pada saat perangkat titik akhir audio membaca posisi perangkat (*pu64Position) sebagai respons terhadap panggilan GetPosition . Metode ini mengonversi nilai penghitung menjadi unit waktu 100 nanodetik sebelum menulisnya ke *pu64QPCPosition. Parameter ini bisa NULL jika klien tidak memerlukan nilai penghitung kinerja.

Nilai kembali

Jika metode berhasil dan mendapatkan pembacaan posisi yang akurat, metode akan mengembalikan S_OK. Jika metode berhasil tetapi durasi panggilan cukup lama untuk mengurangi akurasi pembacaan posisi, metode mengembalikan S_FALSE. Jika gagal, kemungkinan kode pengembalian menyertakan, tetapi tidak terbatas pada, nilai yang diperlihatkan dalam tabel berikut.

Menampilkan kode	Deskripsi
E_POINTER	Parameter pu64Position adalah NULL.
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_SERVICE_NOT_RUNNING	Layanan audio Windows tidak berjalan.

Keterangan

Merender atau menangkap klien yang perlu mengekspos jam berdasarkan pemutaran streaming saat ini atau posisi rekaman dapat menggunakan metode ini untuk memperoleh jam tersebut.

Metode ini mengambil dua nilai posisi aliran yang berkorelasi:

Posisi perangkat. Klien mendapatkan posisi perangkat melalui parameter output pu64Position. Ini adalah posisi aliran sampel yang saat ini diputar melalui speaker (untuk aliran penyajian) atau direkam melalui mikrofon (untuk aliran pengambilan).
Penghitung kinerja. Klien mendapatkan penghitung kinerja melalui parameter output pu64QPCPosition. Ini adalah nilai penghitung yang diperoleh metode dengan memanggil fungsi QueryPerformanceCounter pada saat perangkat titik akhir audio merekam posisi aliran (*pu64Position). Perhatikan bahwa GetPosition mengonversi nilai penghitung menjadi 100 unit waktu nanodetik.

Posisi perangkat tidak berarti kecuali dikombinasikan dengan frekuensi perangkat yang dilaporkan oleh metode IAudioClock::GetFrequency . Alasannya adalah bahwa unit tempat posisi perangkat untuk aliran yang berbeda dinyatakan mungkin bervariasi sesuai dengan faktor-faktor seperti apakah aliran dibuka dalam mode bersama atau mode eksklusif. Namun, frekuensi f yang diperoleh dari GetFrequency selalu dinyatakan dalam unit yang kompatibel dengan frekuensi p posisi perangkat. Dengan demikian, offset relatif aliran dalam hitungan detik selalu dapat dihitung sebagai p/f.

Posisi perangkat adalah offset relatif aliran. Artinya, ini ditentukan sebagai offset dari awal aliran. Posisi perangkat dapat dianggap sebagai offset ke dalam buffer ideal yang berisi seluruh aliran dan berdampingan dari awal hingga akhir.

Mengingat posisi perangkat dan penghitung kinerja pada saat panggilan GetPosition , klien dapat memberikan perkiraan yang lebih tepat waktu dari posisi perangkat pada waktu yang sedikit kemudian dengan memanggil QueryPerformanceCounter untuk mendapatkan penghitung kinerja saat ini, dan mengekstrapolasi posisi perangkat berdasarkan seberapa jauh penghitung telah maju sejak posisi perangkat asli dicatat. Klien dapat memanggil fungsi QueryPerformanceFrequency untuk menentukan frekuensi jam yang menaikkan penghitung. Sebelum membandingkan nilai penghitung mentah yang diperoleh dari QueryPerformanceCounter dengan nilai yang ditulis dengan *pu64QPCPosition by GetPosition, konversikan nilai penghitung mentah menjadi unit waktu 100-nanodetik sebagai berikut:

Kalikan nilai penghitung mentah dengan 10.000.000.
Bagi hasilnya dengan frekuensi penghitung yang diperoleh dari QueryPerformanceFrequency.

Untuk informasi selengkapnya tentang QueryPerformanceCounter dan QueryPerformanceFrequency, lihat dokumentasi Windows SDK.

Segera setelah pembuatan aliran baru, posisi perangkat adalah 0. Setelah panggilan ke metode IAudioClient::Start , posisi perangkat akan mengalami kenaikan pada tingkat yang seragam. Metode IAudioClient::Stop membekukan posisi perangkat, dan panggilan Mulai berikutnya menyebabkan posisi perangkat untuk melanjutkan peningkatan dari nilainya pada saat panggilan Berhenti . Panggilan ke IAudioClient::Reset, yang seharusnya hanya terjadi saat aliran dihentikan, mengatur ulang posisi perangkat ke 0.

Ketika aliran penyajian baru atau reset awalnya mulai berjalan, posisi perangkatnya mungkin tetap 0 selama beberapa milidetik hingga data audio memiliki waktu untuk menyebar dari buffer titik akhir ke perangkat titik akhir penyajian. Posisi perangkat berubah dari 0 menjadi nilai bukan nol saat data mulai diputar melalui perangkat.

Pembacaan perangkat berturut-turut meningkat secara monoton. Meskipun posisi perangkat mungkin tidak berubah di antara dua pembacaan berturut-turut, posisi perangkat tidak pernah berkurang dari satu pembacaan ke pembacaan berikutnya.

Parameter pu64Position harus berupa pointer non-NULL yang valid atau metode akan gagal dan mengembalikan kode kesalahan E_POINTER.

Pengukuran posisi terkadang mungkin tertunda oleh peristiwa berprioritas tinggi yang terputus-terputus. Peristiwa ini mungkin tidak terkait dengan audio. Dalam kasus aliran mode eksklusif, metode dapat mengembalikan S_FALSE alih-alih S_OK jika metode berhasil tetapi durasi panggilan cukup lama untuk mengurangi akurasi posisi yang dilaporkan. Ketika ini terjadi, penelepon memiliki opsi untuk memanggil metode lagi untuk mencoba mengambil posisi yang lebih akurat (seperti yang ditunjukkan oleh nilai pengembalian S_OK). Namun, penelepon harus menghindari melakukan pengujian ini dalam perulangan tak terbatas jika metode secara konsisten mengembalikan S_FALSE.

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