Éléments internes de bibliothèque

Cette rubrique décrit la conception interne de la bibliothèque DirectXMath.

• Conventions d’appel
• Équivalence des types de la bibliothèque graphique
• Constantes globales dans la bibliothèque DirectXMath
• Windows SSE Vs SSE2
• Variantes de routines
• Incohérences entre plateformes
• Extensions spécifiques à la plateforme
• Rubriques connexes

Conventions d’appel

Pour améliorer la portabilité et optimiser la disposition des données, vous devez utiliser les conventions d’appel appropriées pour chaque plateforme prise en charge par la bibliothèque DirectXMath. Plus précisément, lorsque vous passez des objets XMVECTOR en tant que paramètres, qui sont définis comme étant alignés sur une limite de 16 octets, il existe différents ensembles d’exigences d’appel, selon la plateforme cible :

Pour Windows 32 bits

Pour Windows 32 bits, deux conventions d’appel sont disponibles pour le passage efficace des valeurs __m128 (qui implémente XMVECTOR sur cette plateforme). La norme est __fastcall, qui peut passer les trois premières valeurs __m128 (instances de XMVECTOR) en tant qu’arguments d’une fonction dans un registre SSE/SSE2. __fastcall passe les arguments restants via la pile.

Les compilateurs plus récents de Microsoft Visual Studio prennent en charge une nouvelle convention d’appel, __vectorcall, qui peut passer jusqu’à six valeurs __m128 (instances de XMVECTOR) en tant qu’arguments d’une fonction dans un registre SSE/SSE2. Il peut également passer des agrégats vectoriels hétérogènes (également connus sous le nom de XMMATRIX) via les registres SSE/SSE2 s’il y a suffisamment de place.

Pour les éditions 64 bits de Windows

Pour Windows 64 bits, deux conventions d’appel sont disponibles pour le passage efficace des valeurs __m128. La norme est __fastcall, qui passe toutes les valeurs __m128 sur la pile.

Les compilateurs Visual Studio plus récents prennent en charge la convention d’appel __vectorcall, qui peut passer jusqu’à six valeurs __m128 (instances de XMVECTOR) en tant qu’arguments d’une fonction dans un registre SSE/SSE2. Il peut également passer des agrégats vectoriels hétérogènes (également connus sous le nom de XMMATRIX) via les registres SSE/SSE2 s’il y a suffisamment de place.

Pour Windows sur ARM

Windows sur ARM & ARM64 prend en charge le passage des quatre premières valeurs __n128 (instances de XMVECTOR) en registre.

Solution DirectXMath

Les alias FXMVECTOR, GXMVECTOR, HXMVECTOR, et CXMVECTOR prennent en charge ces conventions :

• Utilisez l’alias FXMVECTOR pour passer jusqu’aux trois premières instances de XMVECTOR utilisées comme arguments d’une fonction.
• Utilisez l’alias GXMVECTOR pour passer la 4ème instance d’un XMVECTOR utilisé comme argument d’une fonction.
• Utilisez l’alias HXMVECTOR pour passer les 5ème et 6ème instances d’un XMVECTOR utilisé comme argument d’une fonction. Pour plus d’informations sur les considérations supplémentaires, veuillez consulter la documentation de __vectorcall.
• Utilisez l’alias CXMVECTOR pour passer toute autre instance de XMVECTOR utilisée comme argument.

En raison des limitations de __vectorcall, nous recommandons de ne pas utiliser GXMVECTOR ou HXMVECTOR pour les constructeurs C++. Utilisez simplement FXMVECTOR pour les trois premières valeurs XMVECTOR, puis utilisez CXMVECTOR pour le reste.

Les alias FXMMATRIX et CXMMATRIX aident à profiter du passage d’argument HVA avec __vectorcall.

• Utilisez l’alias FXMMATRIX pour passer le premier XMMATRIX comme argument à la fonction. Cela suppose que vous n’avez pas plus de deux arguments FXMVECTOR ou plus de deux arguments float, double ou FXMVECTOR à la « droite » de la matrice. Pour plus d’informations sur les considérations supplémentaires, veuillez consulter la documentation de __vectorcall.
• Sinon, utilisez l’alias CXMMATRIX.

En raison des limitations de __vectorcall, nous recommandons de ne jamais utiliser FXMMATRIX pour les constructeurs C++. Utilisez simplement CXMMATRIX.

En plus des alias de type, vous devez également utiliser l’annotation XM_CALLCONV pour vous assurer que la fonction utilise la convention d’appel appropriée (__fastcall versus __vectorcall) en fonction de votre compilateur et de votre architecture. En raison des limitations de __vectorcall, nous recommandons de ne pas utiliser XM_CALLCONV pour les constructeurs C++.

Voici quelques exemples de déclarations qui illustrent cette convention :

XMMATRIX XM_CALLCONV XMMatrixLookAtLH(FXMVECTOR EyePosition, FXMVECTOR FocusPosition, FXMVECTOR UpDirection);

XMMATRIX XM_CALLCONV XMMatrixTransformation2D(FXMVECTOR ScalingOrigin,  float ScalingOrientation, FXMVECTOR Scaling, FXMVECTOR RotationOrigin, float Rotation, GXMVECTOR Translation);

void XM_CALLCONV XMVectorSinCos(XMVECTOR* pSin, XMVECTOR* pCos, FXMVECTOR V);

XMVECTOR XM_CALLCONV XMVectorHermiteV(FXMVECTOR Position0, FXMVECTOR Tangent0, FXMVECTOR Position1, GXMVECTOR Tangent1, HXMVECTOR T);

XMMATRIX(FXMVECTOR R0, FXMVECTOR R1, FXMVECTOR R2, CXMVECTOR R3)

XMVECTOR XM_CALLCONV XMVector2Transform(FXMVECTOR V, FXMMATRIX M);

XMMATRIX XM_CALLCONV XMMatrixMultiplyTranspose(FXMMATRIX M1, CXMMATRIX M2);

Pour prendre en charge ces conventions d’appel, ces alias de type sont définis comme suit (les paramètres doivent être passés par valeur pour que le compilateur les considère pour le passage en registre) :

Pour les applications Windows 32 bits

Lorsque vous utilisez __fastcall :

typedef const XMVECTOR  FXMVECTOR;
typedef const XMVECTOR& GXMVECTOR;
typedef const XMVECTOR& HXMVECTOR;
typedef const XMVECTOR& CXMVECTOR;
typedef const XMMATRIX& FXMMATRIX;
typedef const XMMATRIX& CXMMATRIX;

Lorsque vous utilisez __vectorcall :

typedef const XMVECTOR  FXMVECTOR;
typedef const XMVECTOR  GXMVECTOR;
typedef const XMVECTOR  HXMVECTOR;
typedef const XMVECTOR& CXMVECTOR;
typedef const XMMATRIX  FXMMATRIX;
typedef const XMMATRIX& CXMMATRIX;

Pour les applications Windows natives 64 bits

Lorsque vous utilisez __fastcall :

typedef const XMVECTOR& FXMVECTOR;
typedef const XMVECTOR& GXMVECTOR;
typedef const XMVECTOR& HXMVECTOR;
typedef const XMVECTOR& CXMVECTOR;
typedef const XMMATRIX& FXMMATRIX;
typedef const XMMATRIX& CXMMATRIX;

Lorsque vous utilisez __vectorcall :

typedef const XMVECTOR  FXMVECTOR;
typedef const XMVECTOR  GXMVECTOR;
typedef const XMVECTOR  HXMVECTOR;
typedef const XMVECTOR& CXMVECTOR;
typedef const XMMATRIX  FXMMATRIX;
typedef const XMMATRIX& CXMMATRIX;

Windows sur ARM

typedef const XMVECTOR  FXMVECTOR;
typedef const XMVECTOR  GXMVECTOR;
typedef const XMVECTOR& CXMVECTOR;
typedef const XMMATRIX& FXMMATRIX;
typedef const XMMATRIX& CXMMATRIX;

Équivalence des types de la bibliothèque graphique

Pour prendre en charge l’utilisation de la bibliothèque DirectXMath, de nombreux types et structures de la bibliothèque DirectXMath sont équivalents aux implémentations Windows des types D3DDECLTYPE et D3DFORMAT, ainsi que des types DXGI_FORMAT.

Constantes globales dans la bibliothèque DirectXMath

Pour réduire la taille du segment de données, la bibliothèque DirectXMath utilise la macro XMGLOBALCONST pour utiliser un certain nombre de constantes internes globales dans son implémentation. Par convention, ces constantes globales internes sont préfixées par g_XM. En règle générale, elles sont l’un des types suivants : XMVECTORU32, XMVECTORF32, ou XMVECTORI32.

Ces constantes globales internes sont susceptibles de changer dans les futures révisions de la bibliothèque DirectXMath. Utilisez les fonctions publiques qui encapsulent les constantes lorsque cela est possible plutôt que l’utilisation directe des valeurs globales g_XM. Vous pouvez également déclarer vos propres constantes globales en utilisant XMGLOBALCONST.

Windows SSE Vs SSE2

L’ensemble d’instructions SSE ne prend en charge que les vecteurs en virgule flottante simple précision. DirectXMath doit utiliser l’ensemble d’instructions SSE2 pour fournir une prise en charge des vecteurs d’entiers. SSE2 est pris en charge par tous les processeurs Intel depuis l’introduction du Pentium 4, tous les processeurs AMD K8 et ultérieurs, et tous les processeurs compatibles x64.

Variantes de routines

Il existe plusieurs variantes des fonctions DirectXMath qui facilitent votre travail :

• Fonctions de comparaison pour créer une ramification conditionnelle complexe basée sur un plus petit nombre d’opérations de comparaison de vecteurs. Le nom de ces fonctions se termine par « R », comme XMVector3InBoundsR. Les fonctions renvoient un enregistrement de comparaison sous forme de valeur de retour UINT ou en tant que paramètre de sortie UINT. Vous pouvez utiliser les macros XMComparision* pour tester la valeur.
• Fonctions batch pour effectuer des opérations de type batch sur des tableaux de vecteurs plus grands. Le nom de ces fonctions se termine par « Stream », comme XMVector3TransformStream. Les fonctions opèrent sur un tableau d’entrées et génèrent un tableau de sorties. En règle générale, elles prennent une foulée d’entrée et de sortie.
• Fonctions d’estimation qui implémentent une estimation plus rapide au lieu d’un résultat plus lent et plus précis. Le nom de ces fonctions se termine par « Est », comme XMVector3NormalizeEst. L’impact sur la qualité et les performances de l’utilisation de l’estimation varie d’une plateforme à l’autre, mais nous vous recommandons d’utiliser les variantes d’estimation pour le code sensible aux performances.

Incohérences entre plateformes

La bibliothèque DirectXMath est destinée à être utilisée dans des applications graphiques sensibles aux performances et des jeux. Par conséquent, l’implémentation est conçue pour une vitesse optimale lors du traitement normal sur toutes les plateformes prises en charge. Les résultats dans des conditions limites, en particulier ceux qui génèrent des spécificités en virgule flottante, sont susceptibles de varier d’une cible à l’autre. Ce comportement dépendra également d’autres paramètres d’exécution, tels que le mot de contrôle x87 pour la cible Windows 32 bits sans intrinsics ou le mot de contrôle SSE pour les versions Windows 32 bits et 64 bits. De plus, il y aura des différences dans les conditions limites entre les différents fournisseurs de CPU.

N’utilisez pas DirectXMath dans des applications scientifiques ou autres où la précision numérique est primordiale. De plus, cette limitation se reflète dans l’absence de prise en charge des calculs à double ou autre précision étendue.

Extensions spécifiques à la plateforme

La bibliothèque DirectXMath est destinée à simplifier la programmation SIMD en C++ en fournissant un excellent support pour les plateformes x86, x64 et Windows RT en utilisant des instructions intrinsèques largement prises en charge (SSE2 et ARM-NEON).

Il y a cependant des moments où les instructions spécifiques à la plateforme peuvent s’avérer bénéfiques. En raison de la façon dont DirectXMath est implémenté, il est dans de nombreux cas trivial d’utiliser les types DirectXMath directement dans les instructions intrinsèques prises en charge par le compilateur standard, et d’utiliser DirectXMath comme chemin de secours pour les plateformes qui ne prennent pas en charge l’instruction étendue.

Par exemple, voici un exemple simplifié de l’utilisation de l’instruction de produit scalaire SSE 4.1. Notez que vous devez explicitement protéger le chemin de code pour éviter de générer des exceptions d’instruction non valides à l’exécution. Assurez-vous que les chemins de code effectuent un travail suffisant pour justifier le coût supplémentaire de la bifurcation, de la complexité de la maintenance de plusieurs chemins de code, etc.

#include <Windows.h>
#include <stdio.h>

#include <DirectXMath.h>

#include <intrin.h>
#include <smmintrin.h>

using namespace DirectX;

bool g_bSSE41 = false;

void DetectCPUFeatures()
{
#ifndef _M_ARM
   // See __cpuid documentation for more information

   int CPUInfo[4] = {-1};
#if defined(__clang__) || defined(__GNUC__)
   __cpuid(0, CPUInfo[0], CPUInfo[1], CPUInfo[2], CPUInfo[3]);
#else
   __cpuid(CPUInfo, 0);
#endif

   if ( CPUInfo[0] >= 1 )
   {
#if defined(__clang__) || defined(__GNUC__)
        __cpuid(1, CPUInfo[0], CPUInfo[1], CPUInfo[2], CPUInfo[3]);
#else
        __cpuid(CPUInfo, 1);
#endif

       if ( CPUInfo[2] & 0x80000 )
           g_bSSE41 = true;
   }
#endif
}

int main()
{
   if ( !XMVerifyCPUSupport() )
       return -1;

   DetectCPUFeatures();

   ...

   XMVECTORF32 v1 = { 1.f, 2.f, 3.f, 4.f };
   XMVECTORF32 v2 = { 5.f, 6.f, 7.f, 8.f };

   XMVECTOR r2, r3, r4;

   if ( g_bSSE41 )
   {
#ifndef _M_ARM
       r2 = _mm_dp_ps( v1, v2, 0x3f );
       r3 = _mm_dp_ps( v1, v2, 0x7f );
       r4 = _mm_dp_ps( v1, v2, 0xff );
#endif
   }
   else
   {
       r2 = XMVector2Dot( v1, v2 );
       r3 = XMVector3Dot( v1, v2 );
       r4 = XMVector4Dot( v1, v2 );
   }

   ...

   return 0;
}

Pour plus d’informations sur les extensions spécifiques à la plateforme, veuillez consulter :

DirectXMath : SSE, SSE2 et ARM-NEON
DirectXMath : SSE3 et SSSE3
DirectXMath : SSE4.1 et SSE4.2
DirectXMath : AVX
DirectXMath : F16C et FMA
DirectXMath : AVX2
DirectXMath : ARM64

Rubriques connexes

Guide de programmation DirectXMath