Méthode IAudioRenderClient ::GetBuffer (audioclient.h)

Article
02/23/2024

Récupère un pointeur vers l’espace disponible suivant dans la mémoire tampon du point de terminaison de rendu dans lequel l’appelant peut écrire un paquet de données.

Syntaxe

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

Paramètres

[in] NumFramesRequested

Nombre d’images audio dans le paquet de données que l’appelant prévoit d’écrire dans l’espace demandé dans la mémoire tampon. Si l’appel réussit, la taille de la zone tampon pointée par *ppData correspond à la taille spécifiée dans NumFramesRequested.

[out] ppData

Pointeur vers une variable de pointeur dans laquelle la méthode écrit l’adresse de départ de la zone de mémoire tampon dans laquelle l’appelant écrit le paquet de données.

Valeur retournée

Si la méthode réussit, retourne S_OK. En cas d’échec, les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.

Code de retour	Description
AUDCLNT_E_BUFFER_ERROR	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.
AUDCLNT_E_BUFFER_TOO_LARGE	La valeur NumFramesRequested dépasse l’espace tampon disponible (taille de mémoire tampon moins taille de remplissage).
AUDCLNT_E_BUFFER_SIZE_ERROR	Le flux est en mode exclusif et utilise la mise en mémoire tampon pilotée par les événements, mais le client a tenté d’obtenir un paquet qui n’était pas la taille de la mémoire tampon.
AUDCLNT_E_OUT_OF_ORDER	Un appel IAudioRenderClient ::GetBuffer précédent est toujours en vigueur.
AUDCLNT_E_DEVICE_INVALIDATED	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.
AUDCLNT_E_BUFFER_OPERATION_PENDING	Impossible d’accéder à la mémoire tampon, car une réinitialisation de flux est en cours.
AUDCLNT_E_SERVICE_NOT_RUNNING	Le service audio Windows n’est pas en cours d’exécution.
E_POINTER	Le paramètre ppData a la valeur NULL.

Remarques

L’appelant peut demander une taille de paquet inférieure ou égale à la quantité d’espace disponible dans la mémoire tampon (sauf dans le cas d’un flux en mode exclusif qui utilise la mise en mémoire tampon pilotée par les événements ; pour plus d’informations, consultez IAudioClient ::Initialize). L’espace disponible correspond simplement à la taille de la mémoire tampon moins la quantité de données dans la mémoire tampon déjà en file d’attente pour être lues. Si l’appelant spécifie une valeur NumFramesRequested qui dépasse l’espace disponible dans la mémoire tampon, l’appel échoue et retourne le code d’erreur AUDCLNT_E_BUFFER_TOO_LARGE.

Le client est responsable de l’écriture d’une quantité suffisante de données dans la mémoire tampon pour éviter que des problèmes ne se produisent dans le flux audio. Pour plus d’informations sur les exigences en matière de mise en mémoire tampon, consultez IAudioClient ::Initialize.

Après avoir obtenu un paquet de données en appelant GetBuffer, le client remplit le paquet avec des données de rendu et envoie le paquet au moteur audio en appelant la méthode IAudioRenderClient ::ReleaseBuffer .

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.

Pour les tailles de paquets différentes de zéro, le client doit appeler alternativement GetBuffer et ReleaseBuffer. Chaque appel GetBuffer doit être suivi d’un appel ReleaseBuffer correspondant. Une fois que le client a appelé GetBuffer pour acquérir un paquet de données, le client ne peut pas acquérir le paquet de données suivant tant qu’il n’a pas appelé ReleaseBuffer pour libérer le paquet précédent. 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.

La taille d’une image audio est spécifiée par le membre nBlockAlign de la structure WAVEFORMATEX que le client obtient en appelant la méthode IAudioClient ::GetMixFormat .

Si l’appelant définit NumFramesRequested = 0, la méthode retourne status code S_OK mais n’écrit pas dans la variable vers laquelle pointe le paramètre ppData.

Les clients doivent éviter les retards excessifs entre l’appel GetBuffer qui acquiert une mémoire tampon et l’appel ReleaseBuffer qui libère la mémoire tampon. 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’une mémoire tampon pendant plus d’une période risquent de perdre des exemples de données.

Dans Windows 7, 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 des exemples de code qui appellent la méthode GetBuffer , consultez les rubriques suivantes :

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