Elementos internos da biblioteca

Este tópico descreve o design interno da biblioteca DirectXMath.

• Convenções de chamada
• Equivalência de tipo de biblioteca gráfica
• Constantes globais na biblioteca DirectXMath
• Windows SSE versus SSE2
• Variantes de rotina
• Inconsistências de plataforma
• Extensões específicas da plataforma
• Tópicos relacionados

Convenções de chamada

Para aprimorar a portabilidade e otimizar o layout de dados, você precisa usar as convenções de chamada adequadas para cada plataforma compatível com a biblioteca DirectXMath. Especificamente, quando você passa objetos XMVECTOR como parâmetros, que são definidos como alinhados em um limite de 16 bytes, há diferentes conjuntos de requisitos de chamada, dependendo da plataforma de destino:

Para Windows de 32 bits

Para Windows de 32 bits, há duas convenções de chamada disponíveis para a passagem eficiente de valores de __m128 (que implementa XMVECTOR nessa plataforma). O padrão é __fastcall, que pode passar os três primeiros valores __m128 (instâncias XMVECTOR) como argumentos para uma função em um registro SSE/SSE2. __fastcall passa os argumentos restantes pela pilha.

Os compiladores mais recentes do Microsoft Visual Studio oferecem suporte a uma nova convenção de chamada, __vectorcall, que pode passar até seis valores __m128 (instâncias XMVECTOR) como argumentos para uma função em um registro SSE/SSE2. Também pode passar agregados vetoriais heterogêneos (também conhecidos como XMMATRIX) por meio de registros SSE/SSE2 se houver espaço suficiente.

Para edições de 64 bits do Windows

Para Windows de 64 bits, há duas convenções de chamada disponíveis para a passagem eficiente de valores __m128. O padrão é __fastcall, que passa todos os valores __m128 na pilha.

Os compiladores mais recentes do Visual Studio oferecem suporte à convenção de chamada __vectorcall, que pode passar até seis valores __m128 (instâncias XMVECTOR) como argumentos para uma função em um registro SSE/SSE2. Também pode passar agregados vetoriais heterogêneos (também conhecidos como XMMATRIX) por meio de registros SSE/SSE2 se houver espaço suficiente.

Para Windows no ARM

O Windows no ARM e no ARM64 oferece suporte à passagem dos quatro primeiros valores de __n128 (instâncias XMVECTOR) no registro.

Solução DirectXMath

Os aliases FXMVECTOR, GXMVECTOR, HXMVECTOR e CXMVECTOR oferecem suporte a estas convenções:

• Use o alias FXMVECTOR para passar para as três primeiras instâncias de XMVECTOR usadas como argumentos para uma função.
• Use o alias GXMVECTOR para passar a 4ª instância de um XMVECTOR usada como argumento para uma função.
• Use o alias HXMVECTOR para passar a 5ª e a 6ª instâncias de um XMVECTOR usadas como argumento para uma função. Para obter informações sobre considerações adicionais, consulte a documentação do __vectorcall.
• Use o alias CXMVECTOR para passar quaisquer outras instâncias de XMVECTOR usadas como argumentos.

Devido às limitações com __vectorcall, recomendamos que você não use GXMVECTOR ou HXMVECTOR para construtores C++. Use apenas FXMVECTOR para os três primeiros valores XMVECTOR e, depois, use CXMVECTOR para o restante.

Os aliases FXMMATRIX e CXMMATRIX ajudam a oferecer suporte ao aproveitamento do argumento HVA que passa com __vectorcall.

• Use o alias FXMMATRIX para passar o primeiro XMMATRIX como um argumento para a função. Isso pressupõe que você não tenha mais de dois argumentos FXMVECTOR ou mais de dois argumentos float, double ou FXMVECTOR à "direita" da matriz. Para obter informações sobre considerações adicionais, consulte a documentação do __vectorcall.
• Caso contrário, use o alias CXMMATRIX.

Devido às limitações com __vectorcall, recomendamos que você nunca use FXMMATRIX para construtores C++. Use apenas CXMMATRIX.

Além dos aliases de tipo, você também deve usar a anotação XM_CALLCONV para garantir que a função use a convenção de chamada adequada (__fastcall versus __vectorcall) com base no compilador e na arquitetura. Devido às limitações com __vectorcall, recomendamos que você não use XM_CALLCONV para construtores C++.

Veja a seguir exemplos de declarações que ilustram essa convenção:

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);

Para oferecer suporte a essas convenções de chamada, esses aliases de tipo são definidos da seguinte forma (os parâmetros devem ser passados por valor para que o compilador os considere para passagem no registro):

Para aplicativos do Windows de 32 bits

Quando você usa __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;

Quando você usa __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;

Para aplicativos nativos do Windows de 64 bits

Quando você usa __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;

Quando você usa __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 no ARM

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

Equivalência de tipo de biblioteca gráfica

Para oferecer suporte ao uso da biblioteca DirectXMath, muitos tipos e estruturas da biblioteca DirectXMath são equivalentes às implementações do Windows dos tipos D3DDECLTYPE e D3DFORMAT, bem como dos tipos DXGI_FORMAT.

Constantes globais na biblioteca DirectXMath

Para reduzir o tamanho do segmento de dados, a biblioteca DirectXMath usa a macro XMGLOBALCONST para usar várias constantes internas globais em sua implementação. Por convenção, essas constantes globais internas são prefixadas por g_XM. Geralmente, são de um dos seguintes tipos: XMVECTORU32, XMVECTORF32 ou XMVECTORI32.

Essas constantes globais internas estão sujeitas a alterações em revisões futuras da biblioteca DirectXMath. Use funções públicas que encapsulam as constantes quando possível, em vez do uso direto de valores globais g_XM. Você também pode declarar suas próprias constantes globais usando XMGLOBALCONST.

Windows SSE versus SSE2

O conjunto de instruções SSE fornece suporte apenas para vetores de ponto flutuante de precisão simples. O DirectXMath deve usar o conjunto de instruções SSE2 para fornecer suporte a vetores inteiros. O SSE2 é suportado por todos os processadores Intel desde a introdução do Pentium 4, todos os processadores AMD K8 e posteriores e todos os processadores compatíveis com x64.

Variantes de rotina

Existem diversas variantes de funções DirectXMath que facilitam o seu trabalho:

• Funções de comparação para criar ramificações condicionais complicadas com base em um número menor de operações de comparação de vetores. O nome dessas funções termina em "R", como XMVector3InBoundsR. As funções retornam um registro de comparação como um valor de retorno UINT ou como um parâmetro de saída UINT. Você pode usar as macros XMComparision* para testar o valor.
• Funções de lote para executar operações de estilo de lote em matrizes vetoriais maiores. O nome dessas funções termina em "Stream", como XMVector3TransformStream. As funções operam em uma matriz de entradas e geram uma matriz de saídas. Geralmente, elas têm um stride de entrada e saída.
• Funções de estimativa que implementam uma estimativa mais rápida em vez de um resultado mais lento e preciso. O nome dessas funções termina em "Est", como XMVector3NormalizeEst. O impacto na qualidade e no desempenho do uso da estimativa varia conforme a plataforma, mas recomendamos o uso de variantes de estimativa para código sensível ao desempenho.

Inconsistências de plataforma

A biblioteca DirectXMath destina-se ao uso em aplicativos gráficos e jogos sensíveis ao desempenho. Portanto, a implementação foi desenvolvida para alcançar velocidade ideal durante o processamento normal em todas as plataformas com suporte. Os resultados em condições de limite, especialmente aqueles que geram valores especiais de ponto flutuante, provavelmente variam conforme o alvo. Esse comportamento também dependerá de outras configurações de tempo de execução, como a palavra de controle x87 para o destino sem intrínsecos do Windows de 32 bits ou a palavra de controle SSE para Windows de 32 bits e 64 bits. Além disso, haverá diferenças nas condições de limite entre vários fornecedores de CPU.

Não use o DirectXMath em aplicações científicas ou outras em que a precisão numérica é fundamental. Além disso, essa limitação se reflete na falta de suporte para cálculos de precisão duplos ou outros cálculos de precisão estendida.

Extensões específicas da plataforma

A biblioteca DirectXMath tem como objetivo simplificar a programação C++ SIMD, fornecendo excelente suporte para plataformas x86, x64 e Windows RT usando instruções intrínsecas amplamente suportadas (SSE2 e ARM-NEON).

Porém, há momentos em que as instruções específicas da plataforma podem ser benéficas. Devido à forma como o DirectXMath é implementado, em muitos casos, é trivial usar os tipos DirectXMath diretamente em instruções intrínsecas com suporte do compilador padrão e usar o DirectXMath como caminho alternativo para plataformas que não oferecem suporte à instrução estendida.

Por exemplo, veja a seguir um exemplo simplificado de como aproveitar a instrução de produto escalar SSE 4.1. Observe que você deve proteger explicitamente o caminho do código para evitar a geração de exceções de instrução inválidas em tempo de execução. Certifique-se de que os caminhos de código façam um trabalho significativo o suficiente para justificar o custo adicional de ramificação, a complexidade da manutenção de vários caminhos de código e assim por diante.

#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;
}

Para obter mais informações sobre extensões específicas da plataforma, consulte:

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

Tópicos relacionados

Guia de programação do DirectXMath