Méthode IAudioCaptureClient ::GetBuffer (audioclient.h)
Récupère un pointeur vers le paquet de données disponible suivant dans la mémoire tampon du point de terminaison de capture.
Syntaxe
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Paramètres
[out] ppData
Pointeur vers une variable de pointeur dans laquelle la méthode écrit l’adresse de départ du paquet de données suivant que le client peut lire.
[out] pNumFramesToRead
Pointeur vers une variable UINT32 dans laquelle la méthode écrit le nombre d’images (le nombre d’images audio disponibles dans le paquet de données). Le client doit lire l’intégralité du paquet de données ou aucun de celui-ci.
[out] pdwFlags
Pointeur vers une variable DWORD dans laquelle la méthode écrit les indicateurs status mémoire tampon. La méthode écrit 0 ou la combinaison OR au niveau du bit d’une ou plusieurs des valeurs d’énumération _AUDCLNT_BUFFERFLAGS suivantes :
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
Dans Windows 7 et versions ultérieures du système d’exploitation, cet indicateur peut être utilisé pour la détection des problèmes. Pour démarrer le flux de capture, l’application cliente doit appeler IAudioClient ::Start suivi d’appels à GetBuffer dans une boucle pour lire les paquets de données jusqu’à ce que tous les paquets disponibles dans la mémoire tampon du point de terminaison aient été lus. GetBuffer définit l’indicateur AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY pour indiquer un problème dans la mémoire tampon pointée par ppData.
[out] pu64DevicePosition
Pointeur vers une variable UINT64 dans laquelle la méthode écrit la position de l’appareil de la première image audio dans le paquet de données. La position de l’appareil est exprimée en tant que nombre d’images audio à partir du début du flux. Ce paramètre peut avoir la valeur NULL si le client n’a pas besoin de la position de l’appareil. Pour plus d'informations, consultez la section Notes.
[out] pu64QPCPosition
Pointeur vers une variable UINT64 dans laquelle la méthode écrit la valeur du compteur de performances au moment où le périphérique de point de terminaison audio a enregistré la position de l’appareil de la première image audio dans le paquet de données. La méthode convertit la valeur du compteur en unités de 100 nanosecondes avant de l’écrire dans *pu64QPCPosition. Ce paramètre peut avoir la valeur NULL si le client n’a pas besoin de la valeur du compteur de performances. Pour plus d'informations, consultez la section Notes.
Valeur retournée
Les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.
| Code de retour | Description |
|---|---|
|
L’appel a réussi et *pNumFramesToRead est différent de zéro, ce qui indique qu’un paquet est prêt à être lu. |
|
L’appel a réussi et *pNumFramesToRead est 0, ce qui indique qu’aucune donnée de capture n’est disponible pour être lue. |
|
Windows 7 et versions ultérieures : GetBuffer n’a pas pu récupérer une mémoire tampon de données et *ppData pointe vers NULL. Pour plus d'informations, consultez la section Notes. |
|
Un appel IAudioCaptureClient ::GetBuffer précédent est toujours en vigueur. |
|
Le périphérique de point de terminaison audio a été débranché, ou le matériel audio ou les ressources matérielles associées ont été reconfigurés, désactivés, supprimés ou autrement indisponibles. |
|
Impossible d’accéder à la mémoire tampon, car une réinitialisation de flux est en cours. |
|
Le service audio Windows n’est pas en cours d’exécution. |
|
Le paramètre ppData, pNumFramesToRead ou pdwFlags a la valeur NULL. |
Remarques
Cette méthode récupère le paquet de données suivant à partir de la mémoire tampon du point de terminaison de capture. À un moment donné, la mémoire tampon peut contenir zéro, un ou plusieurs paquets prêts à lire. En règle générale, un thread de traitement de mémoire tampon qui lit les données d’une mémoire tampon de point de terminaison de capture lit tous les paquets disponibles chaque fois que le thread s’exécute.
Pendant le traitement d’un flux de capture audio, l’application cliente appelle alternativement GetBuffer et la méthode IAudioCaptureClient ::ReleaseBuffer . Le client ne peut lire qu’un seul paquet de données à chaque appel GetBuffer . Après chaque appel GetBuffer , le client doit appeler ReleaseBuffer pour libérer le paquet avant que le client puisse à nouveau appeler GetBuffer pour obtenir le paquet suivant.
Au moins deux appels consécutifs à GetBuffer ou à ReleaseBuffer ne sont pas autorisés et échouent avec le code d’erreur AUDCLNT_E_OUT_OF_ORDER. Pour garantir l’ordre correct des appels, un appel GetBuffer et son appel ReleaseBuffer correspondant doivent se produire dans le même thread.
Lors de chaque appel GetBuffer , l’appelant doit obtenir le paquet entier ou aucun de celui-ci. Avant de lire le paquet, l’appelant peut case activée la taille du paquet (disponible via le paramètre pNumFramesToRead) pour s’assurer qu’il dispose de suffisamment d’espace pour stocker le paquet entier.
Au cours de chaque appel ReleaseBuffer , l’appelant indique le nombre d’images audio qu’il lit à partir de la mémoire tampon. Ce nombre doit être la taille de paquet (différente de zéro) ou 0. Si le numéro est 0, l’appel GetBuffer suivant présente à l’appelant le même paquet que dans l’appel GetBuffer précédent.
Après chaque appel GetBuffer , les données du paquet restent valides jusqu’à ce que l’appel ReleaseBuffer suivant libère la mémoire tampon.
Le client doit appeler ReleaseBuffer après un appel GetBuffer qui obtient avec succès un paquet de toute taille autre que 0. Le client a la possibilité d’appeler ou de ne pas appeler ReleaseBuffer pour libérer un paquet de taille 0.
La méthode génère la position de l’appareil et le compteur de performances via les paramètres de sortie pu64DevicePosition et pu64QPCPosition . Ces valeurs fournissent un horodatage pour la première image audio du paquet de données. Par le biais du paramètre de sortie pdwFlags , la méthode indique si la position de l’appareil signalée est valide.
La position de l’appareil que la méthode écrit dans *pu64DevicePosition est la position relative au flux de l’image audio qui est actuellement lue via les haut-parleurs (pour un flux de rendu) ou en cours d’enregistrement via le microphone (pour un flux de capture). La position est exprimée sous la forme du nombre d’images à partir du début du flux. La taille d’une image dans un flux audio est spécifiée par le membre nBlockAlign de la structure WAVEFORMATEX (ou WAVEFORMATEXTENSIBLE) qui spécifie le format du flux. La taille, en octets, d’une image audio est égale au nombre de canaux dans le flux multiplié par la taille de l’exemple par canal. Par exemple, pour un flux stéréo (2 canaux) avec des exemples 16 bits, la taille d’image est de quatre octets.
La valeur du compteur de performances que GetBuffer écrit dans *pu64QPCPosition n’est pas la valeur brute du compteur obtenue à partir de la fonction QueryPerformanceCounter . Si t est la valeur brute du compteur et si f est la fréquence obtenue à partir de la fonction QueryPerformanceFrequency , GetBuffer calcule la valeur du compteur de performances comme suit :
*pu64QPCPosition = 10 000 000.T/F
Le résultat est exprimé en unités de 100 nanosecondes. Pour plus d’informations sur QueryPerformanceCounter et QueryPerformanceFrequency, consultez la documentation du Kit de développement logiciel (SDK) Windows.
Si aucun nouveau paquet n’est actuellement disponible, la méthode définit *pNumFramesToRead = 0 et retourne status code AUDCLNT_S_BUFFER_EMPTY. Dans ce cas, la méthode n’écrit pas dans les variables pointées par les paramètres ppData, pu64DevicePosition et pu64QPCPosition .
Les clients doivent éviter les retards excessifs entre l’appel GetBuffer qui acquiert un paquet et l’appel ReleaseBuffer qui libère le paquet. L’implémentation du moteur audio suppose que l’appel GetBuffer et l’appel ReleaseBuffer correspondant se produisent au cours de la même période de traitement de la mémoire tampon. Les clients qui retardent la publication d’un paquet pendant plus d’une période risquent de perdre des exemples de données.
Dans Windows 7 et versions ultérieures, GetBuffer peut retourner le code d’erreur AUDCLNT_E_BUFFER_ERROR pour un client audio qui utilise la mémoire tampon du point de terminaison en mode exclusif. Cette erreur indique que la mémoire tampon de données n’a pas été récupérée, car un paquet de données n’était pas disponible (*ppData a reçu NULL).
Si GetBuffer retourne AUDCLNT_E_BUFFER_ERROR, le thread qui consomme les exemples audio doit attendre le passage de traitement suivant. Le client peut tirer parti de la conservation d’un nombre d’appels GetBuffer ayant échoué. Si GetBuffer retourne cette erreur à plusieurs reprises, le client peut démarrer une nouvelle boucle de traitement après avoir arrêté le client actuel en appelant IAudioClient ::Stop, IAudioClient ::Reset et en libérant le client audio.
Exemples
Pour obtenir un exemple de code qui appelle la méthode GetBuffer, consultez Capture d’un Stream.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | audioclient.h |
Voir aussi
IAudioCaptureClient, interface