Méthode IAudioClient ::IsFormatSupported (audioclient.h)

  • Article

La méthode IsFormatSupported indique si le périphérique de point de terminaison audio prend en charge un format de flux particulier.

Syntaxe

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

Paramètres

[in] ShareMode

Mode de partage pour le format de flux. Grâce à ce paramètre, le client indique s’il souhaite utiliser le format spécifié en mode exclusif ou en mode partagé. Le client doit définir ce paramètre sur l’une des valeurs d’énumération AUDCLNT_SHAREMODE suivantes :

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

Pointeur vers le format de flux spécifié. Ce paramètre pointe vers un descripteur de format alloué par l’appelant de type WAVEFORMATEX ou WAVEFORMATEXTENSIBLE. Le client écrit une description de format dans cette structure avant d’appeler cette méthode. Pour plus d’informations sur WAVEFORMATEX et WAVEFORMATEXTENSIBLE, consultez la documentation windows DDK.

[out] ppClosestMatch

Pointeur vers une variable pointeur dans laquelle la méthode écrit l’adresse d’une structure WAVEFORMATEX ou WAVEFORMATEXTENSIBLE . Cette structure spécifie le format pris en charge le plus proche du format spécifié par le client via le paramètre pFormat . Pour le mode partagé (autrement dit, si le paramètre ShareMode est AUDCLNT_SHAREMODE_SHARED), définissez ppClosestMatch pour qu’il pointe vers une variable de pointeur non NULL valide. Pour le mode exclusif, définissez ppClosestMatch sur NULL. La méthode alloue le stockage pour la structure. L’appelant est chargé de libérer le stockage, lorsqu’il n’est plus nécessaire, en appelant la fonction CoTaskMemFree . Si l’appel IsFormatSupported échoue et que ppClosestMatch n’a pas la valeur NULL, la méthode définit *ppClosestMatch sur NULL. Pour plus d’informations sur CoTaskMemFree, consultez la documentation du Kit de développement logiciel (SDK) Windows.

Valeur retournée

Code de retour Description
S_OK
 Réussite et le périphérique de point de terminaison audio prend en charge le format de flux spécifié.
S_FALSE
 Réussite avec une correspondance la plus proche du format spécifié.
AUDCLNT_E_UNSUPPORTED_FORMAT
 Réussite, mais le format spécifié n’est pas pris en charge en mode exclusif.
 

Si l’opération échoue, les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.

Code de retour Description
E_POINTER
 Le paramètre pFormat a la valeur NULL, ou ppClosestMatch a la valeur NULL et ShareMode est AUDCLNT_SHAREMODE_SHARED.
E_INVALIDARG
 Le paramètre ShareMode est une valeur autre que AUDCLNT_SHAREMODE_SHARED ou AUDCLNT_SHAREMODE_EXCLUSIVE.
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 rendus indisponibles.
AUDCLNT_E_SERVICE_NOT_RUNNING
 Le service audio Windows n’est pas en cours d’exécution.

Remarques

Cette méthode permet à un client de déterminer, avant d’appeler IAudioClient ::Initialize, si le moteur audio prend en charge un format de flux particulier.

Pour le mode exclusif, IsFormatSupported retourne S_OK si le périphérique de point de terminaison audio prend en charge le format spécifié par l’appelant, ou il retourne AUDCLNT_E_UNSUPPORTED_FORMAT si l’appareil ne prend pas en charge le format. Le paramètre ppClosestMatch peut être NULL. Si elle n’est pas NULL, la méthode écrit NULL dans *ppClosestMatch.

Pour le mode partagé, si le moteur audio prend en charge le format spécifié par l’appelant, IsFormatSupported définit *ppClosestMatch sur NULL et retourne S_OK. Si le moteur audio ne prend pas en charge le format spécifié par l’appelant, mais prend en charge un format similaire, la méthode récupère le format similaire via le paramètre ppClosestMatch et retourne S_FALSE. Si le moteur audio ne prend pas en charge le format spécifié par l’appelant ou un format similaire, la méthode définit *ppClosestMatch sur NULL et retourne AUDCLNT_E_UNSUPPORTED_FORMAT.

En mode partagé, le moteur audio prend toujours en charge le format de mixage, que le client peut obtenir en appelant la méthode IAudioClient ::GetMixFormat . En outre, le moteur audio peut prendre en charge des formats similaires qui ont le même taux d’échantillonnage et le même nombre de canaux que le format de mixage, mais qui diffèrent dans la représentation des valeurs d’exemples audio. Le moteur audio représente des exemples de valeurs en interne sous forme de nombres à virgule flottante, mais si le format spécifié par l’appelant représente des exemples de valeurs sous forme d’entiers, le moteur audio peut généralement effectuer une conversion entre les valeurs d’échantillon d’entiers et sa représentation à virgule flottante interne.

Le moteur audio peut être en mesure de prendre en charge un éventail encore plus large de formats en mode partagé si le package d’installation de l’appareil audio inclut un objet de traitement audio (APO) à effets locaux (LFX) qui peut gérer les conversions de format. Une APO LFX est un module logiciel qui effectue un traitement spécifique à l’appareil d’un flux audio. Le générateur de graphiques audio dans le service audio Windows insère l’APO LFX dans le flux entre chaque client et le moteur audio. Lorsqu’un client appelle la méthode IsFormatSupported et que la méthode détermine qu’une apo LFX est installée pour une utilisation avec l’appareil, la méthode dirige la requête vers l’apo LFX, qui indique si elle prend en charge le format spécifié par l’appelant.

Par exemple, une apo LFX particulière peut accepter un flux de son surround à 6 canaux à partir d’un client et convertir le flux dans un format stéréo qui peut être lu via un casque. En règle générale, une apo LFX prend uniquement en charge les formats clients avec des taux d’échantillonnage qui correspondent au taux d’échantillonnage du format de combinaison.

Pour plus d’informations sur les API, consultez Objets de traitement audio Windows. Pour plus d’informations sur la méthode IsFormatSupported , consultez Formats d’appareil.

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

IAudioClient, interface

IAudioClient ::GetMixFormat

IAudioClient ::Initialize