Portage des nuanceurs de FXC vers DXC - XBOX Game Development Documentation

Introduction

Cette rubrique sert de point de référence pour le portage de vos nuanceurs HLSL (High-Level Shader Language) existants de D3DCompiler (FXC) vers DXCompiler (DXC). Plus précisément, elle fournit des informations sur les points suivants :

Activer certains anciens comportements de compilation de FXC qui sont désactivés par défaut dans DXC. DXC les prend en charge au moyen des indicateurs de compilation suivants :
- -Gec : active la rétrocompatibilité avec Direct3D 9 (par exemple, active la prise en charge de la sémantique COLOR, qui n’est prise en charge que jusqu’à Direct3D 9).
- -HV : active la rétrocompatibilité avec FXC en définissant la version du langage sur 2016 (c’est-à-dire -HV 2016). Cela active une sémantique de langage héritée disponible dans FXC.
- -flegacy-macro-expansion : développe les opérandes avant d’effectuer l’opération de collage de jetons (comportement de FXC).
- -flegacy-resource-reservation : réserve les affectations explicites de registres inutilisées pour la compatibilité avec le modèle de nuanceur 5.0 et versions antérieures.
- -D __XBOX_PRECOMPILE_ALL_STAGES : sur XBOX Series X|S, la précompilation des nuanceurs est beaucoup plus conservatrice. Les valeurs par défaut de la XBOX One restent inchangées. Pour plus de renseignements, consultez Définitions XBOX.
Fournir des informations sur les anciennes syntaxes HLSL dépréciées qui étaient prises en charge par FXC mais ne le sont plus par DXC.

Modifications de l’interface .dll du compilateur

Nous vous recommandons d’utiliser la nouvelle fonction IDxcCompiler3::Compile pour compiler les nuanceurs DXC. Pour plus de renseignements sur les routines d’assistance qui faciliteront le portage du code existant vers la nouvelle interface, ainsi que des exemples de code, consultez Utilisation de DXC.

Rétrocompatibilité avec les comportements de FXC

Modèle uniquement multiplicatif pour la fonction intrinsèque pow

Par défaut, DXC utilise toujours le modèle log-mul-exp (expliqué ci-après) pour implémenter la fonction pow. En revanche, FXC utilise aussi, dans certains scénarios, le modèle mul-only pour implémenter la fonction pow. Par exemple, pour les petites valeurs constantes de y (comme pow(x, 3)), FXC utilise le modèle mul-only. La fonction pow peut donc produire des résultats différents selon qu’elle est compilée avec FXC ou avec DXC. Par exemple, pour une valeur d’exécution x=0, pow(x,3) donne respectivement NaN et 0 avec DXC et FXC. Pour obtenir le comportement de FXC pour la fonction pow avec DXC, définissez la version du langage sur 2016 (à l’aide de l’indicateur -HV 2016) lors de la compilation.

Exemple d’implémentation de pow à l’aide du modèle log-mul-exp

pow(x,y) = e^(log(x) * y)

Exemple d’implémentation de pow à l’aide du modèle mul-only

pow(x,3) = (x * x) * x

Accès hors limites aux tableaux

Par défaut, DXC génère une erreur lorsqu’il trouve des références à un tableau avec un index constant hors limites. Par exemple, le nuanceur HLSL suivant ne se compile pas et produit le message d’erreur : error: array index 3 is out of bounds. Vous pouvez transformer cette erreur en avertissement en définissant la version du langage sur 2016 (c’est-à-dire à l’aide de l’indicateur -HV 2016), uniquement lorsque l’accès hors limites se produit dans du code inutilisé ou mort.

void main()
{
  uint x[2];
  x[3]=1.f; // Out-of-bound access.
}

Avertissement lorsque l’attribut unroll ne peut pas être respecté

Lorsque l’attribut unroll est appliqué à une boucle et que le nombre d’itérations de la boucle ne peut pas être déterminé à la compilation ou dépasse un certain seuil, DXC ne parvient pas, par défaut, à compiler des nuanceurs tels que le suivant. Pour transformer cet échec en avertissement, définissez la version du langage sur 2016. Lorsque le nuanceur suivant est compilé avec DXC et l’indicateur -HV 2016, il se compile correctement sans dérouler la boucle et génère un message d’avertissement : warning: Could not unroll the loop.

uint main(uint x : IN) : OUT
{
   uint r = 0;
   [unroll]
   for(uint i=0; i<x; i++)
    r+=i;
   return r;
}

Sémantique COLOR

La sémantique COLOR n’est pas prise en charge par défaut dans DXC. Lorsque vous écrivez de nouveaux nuanceurs HLSL ciblant DXC, utilisez plutôt SV_Target. Toutefois, DXC offre aussi la possibilité de compiler des nuanceurs faisant référence à la sémantique COLOR en lui passant l’indicateur -Gec. Par exemple, le code HLSL suivant doit se compiler correctement avec DXC lorsque l’indicateur -Gec est utilisé.

float main() : COLOR
{
    return 1.f;
}

Propriété Length sur les tableaux constants

La propriété Length sur les tableaux constants est prise en charge dans DXC avec l’indicateur -Gec, comme le montre l’exemple suivant.

uint main() : OUT
{
    int x[5];
    return x.Length;
}

Écriture dans les variables globales

Les variables globales sont traitées comme des constantes en HLSL, mais comme FXC, DXC permet aussi d’écrire dans les variables globales avec l’indicateur -Gec, comme le montre l’exemple suivant.

float gvar; // Write enabled with "-Gec"

float4 main(uint a : A) : SV_Target
{
  gvar = a * 2.0f;  
  return (float4) gvar;
}

Réservation de ressources héritée à l’aide de l’indicateur `-flegacy-resource-reservation`

Pour le modèle de nuanceur 5.0 ou antérieur, FXC tenait compte de l’allocation de registres des ressources inutilisées lors de l’allocation des registres des ressources utilisées. Par exemple, lors de la compilation du nuanceur suivant avec FXC en SM5.0 et 5.1, Tex1[1] est lié respectivement à t4 et à t0. Avec DXC, pour obtenir le comportement d’allocation des ressources de FXC avec SM5.0 ou antérieur, utilisez l’indicateur -flegacy-resource-reservation.

Texture2D Tex0[2] : register(t1);
Texture2D Tex1[2];

float4 main() : SV_Target
{
    return Tex1[1].Load((uint3)0);
}

Liaison des ressources avec FXC en SM5.0

// Resource bindings:
//
// Name                                 Type  Format         Dim      HLSL Bind  Count
// ------------------------------ ---------- ------- ----------- -------------- ------
// Tex1[1]                           texture  float4          2d             t4      1

Liaison des ressources avec FXC en SM5.1

// Resource bindings:
//
// Name                                 Type  Format         Dim      ID      HLSL Bind  Count
// ------------------------------ ---------- ------- ----------- ------- -------------- ------
// Tex1                              texture  float4          2d      T0             t0      2

Liaison des ressources avec DXC en SM6.0 sans l’indicateur `-flegacy-resource-reservation`

// Resource bindings:
//
// Name                                 Type  Format         Dim      ID      HLSL Bind  Count
// ------------------------------ ---------- ------- ----------- ------- -------------- ------
// Tex1                              texture     f32          2d      T0             t0     2

Liaison des ressources avec DXC en SM6.0 avec l’indicateur `-flegacy-resource-reservation`

// Resource bindings:
//
// Name                                 Type  Format         Dim      ID      HLSL Bind  Count
// ------------------------------ ---------- ------- ----------- ------- -------------- ------
// Tex1                              texture     f32          2d      T0             t3     2

Développement de macros hérité à l’aide de l’indicateur `-flegacy-macro-expansion`

Le nuanceur HLSL suivant se compile correctement avec FXC, mais génère une erreur avec DXC, car b##slot est remplacé par bSLOT_VAL au lieu de b3, ce qui fait échouer la compilation. Pour obtenir le comportement de remplacement de jetons de FXC avec DXC, compilez avec l’indicateur supplémentaire « -flegacy-macro-expansion ».

#define SLOT_VAL 3
#define CBUFFER_ALIGNED( name, slot ) cbuffer name : register( b##slot )

CBUFFER_ALIGNED( MyCBuffer, SLOT_VAL )
{
       float4        val;
};

Dans ce cas, vous pouvez éviter d’utiliser l’indicateur -flegacy-macro-expansion en suivant les règles standard du préprocesseur.

#define SLOT_VAL 3
#define PASTE1(a, b) a##b
#define PASTE(a, b) PASTE1(a, b)
#define CBUFFER_ALIGNED( name, slot ) cbuffer name : register( PASTE(b, slot) )
CBUFFER_ALIGNED( MyCBuffer, SLOT_VAL )
{
       float4        val;
};

-flegacy-macro-expansion n’est d’aucune aide lorsque les jetons ne sont pas des arguments de macro, même si fxc les développe quand même. Le code suivant génère une erreur même si -flegacy-macro-expansion est utilisé.

#define C 4
#define A4 float4
#define TYPE A##C

#define FUNC(ty) ty main() : OUT { return 0; }
FUNC(TYPE)

La modification suivante rend le code HLSL conforme aux règles standard du préprocesseur, et l’option -flegacy-macro-expansion n’est plus nécessaire.

#define C 4
#define A4 float4
#define PASTE1(a, b) a##b
#define PASTE(a, b) PASTE1(a, b)
#define TYPE PASTE(A, C)

#define FUNC(ty) ty main() : OUT { return 0; }
FUNC(TYPE)

Comportements de FXC non pris en charge

Effect Framework

Les fonctionnalités liées à l’Effect Framework ne sont plus prises en charge.

Paramètres uniformes sur les fonctions d’entrée

Les paramètres uniformes sur les fonctions d’entrée ne sont plus pris en charge.

Interfaces

Les interfaces ne sont plus prises en charge.

Les fonctions d’échantillonnage de texture propres à une dimension ne sont plus prises en charge

Les fonctions tex1D, tex2D et autres fonctions d’échantillonnage similaires sont maintenant dépréciées. Pour savoir comment effectuer le portage vers les fonctions d’échantillonnage prises en charge, consultez l’exemple suivant.

Exemple utilisant l’ancienne syntaxe d’échantillonnage, qui n’est plus prise en charge

sampler FontTextureSampler : register(s0);
struct VS_OUT
{
   float2 TexCoord0 : TEXCOORD0;
};

float4 PSMain_Unsupported( VS_OUT In ) : SV_Target
{
    return tex2D( FontTextureSampler, In.TexCoord0 ).zyxw; // tex2D is unsupported.
}

Exemple illustrant la syntaxe d’échantillonnage prise en charge

SamplerState FontTextureSampler : register(s0);
Texture2D FontTexture2D : register( t0 ); // Step 1. Declare texture.

struct VS_OUT
{
   float2 TexCoord0 : TEXCOORD0;
};

float4 PSMain( VS_OUT In ) : SV_Target
{
    // Step 2. Use "Sample" method of the texture declared in the previous step.
    return FontTexture2D.Sample( FontTextureSampler, In.TexCoord0 ).zyxw;
}

Chevauchement de sémantiques non pris en charge

DXC interdit l’utilisation de sémantiques en double. Par exemple, le nuanceur suivant ne se compile pas avec DXC.

uint main(uint a : SV_VertexID, uint b : SV_VertexID) : OUT
{
    return a + b;
}

« ConstantBuffer » non pris en charge comme nom de tampon constant

À partir de SM5.1, HLSL prend en charge les tampons constants indexables au moyen de la construction de modèle ConstantBuffer. ConstantBuffer est donc un mot clé réservé et DXC interdit son utilisation comme nom de tampon.

cbuffer ConstantBuffer : register(b0) // ConstantBuffer as buffer name not allowed.
{
 float2 field1;
 float field2;
}

Nous communiquer avec

Pour toute question, demande d’aide ou signalement de problème, vous pouvez nous contacter à l’adresse AskHLSL@microsoft.com.

Voir aussi

Compilateur de nuanceurs

​Introduction

​Modifications de l’interface .dll du compilateur

​Rétrocompatibilité avec les comportements de FXC

​Modèle uniquement multiplicatif pour la fonction intrinsèque pow

​Exemple d’implémentation de pow à l’aide du modèle log-mul-exp

​Exemple d’implémentation de pow à l’aide du modèle mul-only

​Accès hors limites aux tableaux

​Avertissement lorsque l’attribut unroll ne peut pas être respecté

​Sémantique COLOR

​Propriété Length sur les tableaux constants

​Écriture dans les variables globales

​Réservation de ressources héritée à l’aide de l’indicateur -flegacy-resource-reservation

​Liaison des ressources avec FXC en SM5.0

​Liaison des ressources avec FXC en SM5.1

​Liaison des ressources avec DXC en SM6.0 sans l’indicateur -flegacy-resource-reservation

​Liaison des ressources avec DXC en SM6.0 avec l’indicateur -flegacy-resource-reservation

​Développement de macros hérité à l’aide de l’indicateur -flegacy-macro-expansion

​Comportements de FXC non pris en charge

​Effect Framework

​Paramètres uniformes sur les fonctions d’entrée

​Interfaces

​Les fonctions d’échantillonnage de texture propres à une dimension ne sont plus prises en charge

​Exemple utilisant l’ancienne syntaxe d’échantillonnage, qui n’est plus prise en charge

​Exemple illustrant la syntaxe d’échantillonnage prise en charge

​Chevauchement de sémantiques non pris en charge

​« ConstantBuffer » non pris en charge comme nom de tampon constant

​Nous communiquer avec

​Voir aussi