Sémantique

  • Article

Une sémantique est une chaîne attachée à une entrée ou une sortie de nuanceur qui transmet des informations sur l’utilisation prévue d’un paramètre. La sémantique est requise pour toutes les variables transmises entre les phases du nuanceur. La syntaxe d’ajout d’une sémantique à une variable de nuanceur s’affiche ici (Syntaxe de variable (DirectX HLSL)).

En général, les données transmises entre les phases de pipeline sont complètement génériques et ne sont pas interprétées de manière unique par le système ; la sémantique arbitraire est autorisée, ce qui n’a aucune signification particulière. Les paramètres (dans Direct3D 10 et versions ultérieures) qui contiennent ces sémantiques spéciales sont appelés Sémantique système-valeur.

Sémantiques prises en charge dans Direct3D 9 et Direct3D 10 et versions ultérieures

Les types de sémantique suivants sont pris en charge dans Direct3D 9 et Direct3D 10 et versions ultérieures.

Sémantique du nuanceur de vertex

Ces sémantiques ont une signification lorsqu’elles sont attachées à un paramètre de nuanceur de vertex. Ces sémantiques sont prises en charge dans Direct3D 9 et Direct3D 10 et versions ultérieures.

Input Description Type
BINORMAL[n] Binormal float4
BLENDINDICES[n] Indices Blend uint
BLENDWEIGHT[n] Poids Blend float
COLOR[n] Couleur diffuse et spéculaire float4
NORMAL[n] Vecteur normal float4
POSITION[n] Position de vertex dans l’espace objet. float4
POSITIONT Position de vertex transformée. float4
PSIZE[n] Taille d’impression float
TANGENT[n] Tangente float4
TEXCOORD[n] Coordonnées de texture float4
Sortie Description Type
COLOR[n] Couleur diffuse ou spéculaire float4
FOG Brouillard de vertex float
POSITION[n] Position d’un vertex dans un espace homogène. Position de calcul dans l’espace-écran en divisant (x,y,z) par w. Chaque nuanceur de vertex doit écrire un paramètre avec cette sémantique. REMARQUE : cette sémantique est disponible dans Direct3D 9. Pour Direct3D 10 et versions ultérieures, utilisez plutôt SV_Position. float4
PSIZE Taille d’impression float
TESSFACTOR[n] Facteur de tessellateur float

n est un entier facultatif compris entre 0 et le nombre de ressources prises en charge. Par exemple, POSITION0, TEXCOORD1, etc.

Sémantique du nuanceur de pixels

Ces sémantiques ont une signification lorsqu’elles sont attachées à un paramètre d’entrée de nuanceur de pixels. Ces sémantiques sont prises en charge dans Direct3D 9 et Direct3D 10 et versions ultérieures.

Input Description Type
COLOR[n] Couleur diffuse ou spéculaire. float4
TEXCOORD[n] Coordonnées de texture float4
VFACE Scalaire à virgule flottante qui indique une primitive arrière. Une valeur négative est orientée vers l’arrière, tandis qu’une valeur positive est orientée vers la caméra.

Remarque :
Cette sémantique est disponible dans le modèle de nuanceur 3.0 Direct3D 9. Pour Direct3D 10 et versions ultérieures, utilisez plutôt SV_IsFrontFace.


 float
VPOS Emplacement du pixel (x,y) dans l’espace d’écran. Pour convertir un nuanceur Direct3D 9 (qui utilise cette sémantique) en nuanceur Direct3D 10 et version ultérieure, voir Direct3D 9 VPOS et Direct3D 10 SV_Position) float2
Sortie Description Type
COLOR[n] Couleur de sortie float4
DEPTH[n] Profondeur de sortie float

n est un entier facultatif compris entre 0 et le nombre de ressources prises en charge. Par exemple, PSIZE0, COLOR1, etc.

La sémantique COLOR est valide uniquement en mode de compatibilité du nuanceur (autrement dit, lorsque le nuanceur est créé à l’aide de D3D10_SHADER_ENABLE_BACKWARDS_COMPATIBILITY).

Sémantique prise en charge uniquement pour Direct3D 10 et versions ultérieures.

Les types de sémantique suivants ont été récemment introduits pour Direct3D 10 et ne sont pas disponibles pour Direct3D 9.

Sémantique de valeur système

La sémantique de valeur système est une nouveauté pour Direct3D 10. Toutes les valeurs système commencent par un préfixe SV_, SV_POSITION en est un exemple courant, interprété par la phase du rastériseur. Les valeurs système sont valides dans d’autres parties du pipeline. Par exemple, SV_Position peut être spécifié en tant qu’entrée et sortie dans un nuanceur de vertex. Les nuanceurs de pixels peuvent uniquement écrire dans des paramètres avec la sémantique de valeur système SV_Depth et SV_Target.

D’autres valeurs système (SV_VertexID, SV_InstanceID, SV_IsFrontFace) ne peuvent être entrées que dans le premier nuanceur actif du pipeline qui peut interpréter la valeur particulière. Ensuite, la fonction de nuanceur doit transmettre les valeurs aux phases suivantes.

SV_PrimitiveID est une exception à cette règle qui consiste à n’entrer que dans le premier nuanceur actif du pipeline qui peut interpréter la valeur particulière. Le matériel peut fournir la même valeur d’ID en tant qu’entrée à la phase de nuanceur de coque, à la phase de nuanceur de domaine et après la première phase activée, à savoir la phase de nuanceur de géométrie ou de nuanceur de pixels.

Si le pavage est activé, la phase de nuanceur de coque et la phase de nuanceur de domaine sont présentes. Pour un correctif donné, le même PrimitiveID s’applique à l’appel du nuanceur de coque du correctif et à tous les appels de nuanceur de domaine tessellés. Le même PrimitiveID se propage également à la phase active suivante, à savoir l’étape de nuanceur de géométrie ou l’étape de nuanceur de pixels, si elle est activée.

Si les entrées du nuanceur de géométrie SV_PrimitiveID et qu’elles peuvent générer zéro ou une ou plusieurs primitives par appel, le nuanceur doit programmer son propre choix de valeur SV_PrimitiveID pour chaque primitive de sortie si un nuanceur de pixels ultérieur entre SV_PrimtiveID.

Comme autre exemple, SV_PrimitiveID ne peut pas être interprété par la phase de nuanceur de vertex, car un vertex peut être membre de plusieurs primitives.

Ces sémantiques ont été ajoutées à Direct3D 10 et ne sont pas disponibles dans Direct3D 9.

Sémantique de valeur système pour la phase de rastériseur.

Sémantique de valeur système Description Type
SV_ClipDistance[n] Découper les données de distance. Les valeurs SV_ClipDistance sont supposées être une distance signée float32 à un plan. La configuration primitive invoque uniquement la rastérisation sur les pixels pour lesquels la ou les distances de plan interpolées sont >= 0. Plusieurs plans de découpage peuvent être implémentés simultanément, en déclarant plusieurs composants d’un ou plusieurs éléments de vertex comme SV_ClipDistance. Les valeurs combinées de distance de découpage et de suppression sont au plus des composants D3D#_CLIP_OR_CULL_DISTANCE_COUNT dans la plupart des registres D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT. Tous les nuanceurs peuvent lire ou écrire cette valeur, à l’exception du nuanceur de vertex qui peut l’écrire mais ne peut pas la prendre en entrée.
L’attribut clipplanes fonctionne comme SV_ClipDistance mais fonctionne sur l’ensemble du matériel de niveau de fonctionnalité 9_x et versions ultérieures. Pour plus d’informations, consultez Plans de découpage utilisateur sur le matériel de niveau de fonctionnalité 9.
 float
SV_CullDistance[n] Données de distance de découpage. Lorsqu’un ou plusieurs composants du ou des éléments vertex reçoivent cette étiquette, ces valeurs sont toutes supposées être une distance signée float32 à un plan. Les primitives seront complètement ignorées si la ou les distances du plan pour tous les sommets de la primitive sont < 0. Plusieurs plans de suppression peuvent être utilisés simultanément, en déclarant plusieurs composants d’un ou plusieurs éléments de vertex comme SV_CullDistance. Les valeurs combinées de distance de découpage et de suppression sont au plus des composants D3D#_CLIP_OR_CULL_DISTANCE_COUNT dans la plupart des registres D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT. Tous les nuanceurs peuvent lire ou écrire cette valeur, à l’exception du nuanceur de vertex qui peut l’écrire mais ne peut pas la prendre en entrée.
 float
SV_Coverage Masque qui peut être spécifié sur l’entrée, la sortie ou les deux d’un nuanceur de pixels.
Pour SV_Coverage sur un nuanceur de pixels, OUTPUT est pris en charge sur ps_4_1 ou version ultérieure.
Pour SV_Coverage sur un nuanceur de pixels, INPUT nécessite ps_5_0 ou version ultérieure.
uint
SV_Depth Données du tampon de profondeur. Peut être écrit par le nuanceur de pixels. float
SV_DepthGreaterEqual Dans un nuanceur de pixels, permet de sortir la profondeur, tant qu’elle est supérieure ou égale à la valeur déterminée par le rastériseur. Active l’ajustement de la profondeur sans désactiver le Z anticipé. float
SV_DepthLessEqual Dans un nuanceur de pixels, permet de sortir la profondeur, tant qu’elle est inférieure ou égale à la valeur déterminée par le rastériseur. Active l’ajustement de la profondeur sans désactiver le Z anticipé. float
SV_DispatchThreadID Définit le décalage de thread global dans l’appel de Dispatch, conformément à la dimension du groupe. Disponible en tant qu’entrée du nuanceur de calcul. (lecture seule) uint3
SV_DomainLocation Définit l’emplacement sur la coque du point de domaine actuel en cours d’évaluation. Disponible en tant qu’entrée du nuanceur de domaine. (lecture seule) float2|3
SV_GroupID Définit le décalage de groupe dans un appel de Dispatch, conformément à la dimension de ce dernier. Disponible en tant qu’entrée du nuanceur de calcul. (lecture seule) uint3
SV_GroupIndex Fournit un index aplatit pour un thread donné au sein d’un groupe donné. Disponible en tant qu’entrée du nuanceur de calcul. (lecture seule) uint
SV_GroupThreadID Définit le décalage de thread dans l’appel de Dispatch au sein du groupe, conformément à la dimension du groupe. Disponible en tant qu’entrée du nuanceur de calcul. (lecture seule) uint3
SV_GSInstanceID Définit l’instance du nuanceur de géométrie. Disponible en tant qu’entrée du nuanceur de géométrie. L’instance est nécessaire, étant donné qu’un nuanceur de géométrie peut être appelé jusqu’à 32 fois sur la même primitive de géométrie. uint
SV_InnerCoverage Représente les informations de rastérisation conservatrice sous-estimées (c’est-à-dire si un pixel est garanti pour être entièrement couvert). Peut être lu ou écrit par le nuanceur de pixels.
SV_InsideTessFactor Définit la quantité de pavage dans une surface de correctif. Disponible dans le nuanceur de coque pour l’écriture et dans le nuanceur de domaine pour la lecture. float|float[2]
SV_InstanceID Identificateur par instance généré automatiquement par le runtime (voir Utilisation des valeurs générées par le système (Direct3D 10)). Disponible pour tous les nuanceurs.
SV_IsFrontFace Spécifie si un triangle est orienté vers l’avant. Pour les lignes et les points, IsFrontFace a la valeur true. L’exception concerne des lignes dessinées en dehors des triangles (mode maquette fonctionnelle), ce qui définit IsFrontFace de la même façon que la rastérisation du triangle en mode plein. Peut être écrit par le nuanceur de géométrie et lu par le nuanceur de pixels. bool
SV_OutputControlPointID Définit l’index de l’ID du point de contrôle utilisé par un appel du point d’entrée principal du nuanceur de coque. Peut être lu uniquement par le nuanceur de coque. uint
SV_Position Quand SV_Position est déclaré en vue d’une entrée dans un nuanceur, l’un des deux modes d’interpolation suivants peut être spécifié : linearNoPerspective ou linearNoPerspectiveCentroid, ce dernier entraînant la fourniture de valeurs xyzw ancrées à la centroïde lors de l’anticrénelage multi-échantillon. Lorsqu’il est utilisé dans un nuanceur, SV_Position décrit l’emplacement des pixels. Disponible dans tous les nuanceurs pour obtenir le centre des pixels avec un décalage de 0,5. float4
SV_PrimitiveID Identificateur par primitive généré automatiquement par le runtime (voir Utilisation des valeurs générées par le système (Direct3D 10)). Peut être écrit par les nuanceurs de géométrie ou de pixels, et lu par les nuanceurs de géométrie, de pixel, de coque ou de domaine. uint
SV_RenderTargetArrayIndex Index de tableau cible de rendu. Appliqué à la sortie du nuanceur de géométrie et indique la tranche du tableau cible de rendu vers laquelle la primitive sera dessinée par le nuanceur de pixels. SV_RenderTargetArrayIndex est valide uniquement si la cible de rendu est une ressource de tableau. Cette sémantique s’applique uniquement aux primitives. Si une primitive a plusieurs vertex, la valeur du vertex de début est utilisée. Cette valeur indique également la tranche de tableau d’une vue de profondeur/gabarit utilisée à des fins de lecture/d’écriture.
Peut être écrit depuis le nuanceur de géométrie et lu par le nuanceur de pixels.
Si D3D11_FEATURE_DATA_D3D11_OPTIONS3 ::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer est true, SV_RenderTargetArrayIndex est appliqué à n’importe quel nuanceur alimentant le rastériseur.		 uint
SV_SampleIndex Exemples de données d’index de fréquence. Disponible pour être lu ou écrit uniquement par le nuanceur de pixels. uint
SV_StencilRef Représente la valeur de référence du gabarit du nuanceur de pixels actuel. Peut être écrit uniquement par le nuanceur de pixels. uint
SV_Target[n], où 0 <= n <= 7 Valeur de sortie qui sera stockée dans une cible de rendu. L’index indique les 8 cibles de rendu éventuellement liées à l’écriture. La valeur est disponible pour tous les nuanceurs. float[2|3|4]
SV_TessFactor Définit la quantité de pavage sur chaque bord d’un correctif. Disponible pour l’écriture dans le nuanceur de coque et la lecture dans le nuanceur de domaine. float[2|3|4]
SV_VertexID Identificateur par vertex généré automatiquement par le runtime (voir Utilisation des valeurs générées par le système (Direct3D 10)). Disponible en tant qu’entrée du nuanceur de vertex uniquement. uint
SV_ViewportArrayIndex Index de tableau de fenêtre d’affichage. Appliqué à la sortie du nuanceur de géométrie et indique la fenêtre d’affichage à utiliser pour la primitive en cours d’écriture. Peut être lu par le nuanceur de pixels. La primitive sera transformée et clippée par rapport à la fenêtre d’affichage spécifiée par l’index avant de la transférer au rastériseur. Cette sémantique s’applique uniquement aux primitives. Si une primitive a plusieurs vertex, la valeur du vertex de début est utilisée.
Si D3D11_FEATURE_DATA_D3D11_OPTIONS3 ::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer est true, SV_ViewportArrayIndex est appliqué à n’importe quel nuanceur alimentant le rastériseur.		 uint
SV_ShadingRate Définit, par le biais de valeurs de taux d’ombrage, le nombre de pixels écrits par un appel de nuanceur de pixels pour Taux d’ombrage variable niveau 2 ou appareils supérieurs. Peut être lu à partir du nuanceur de pixels. Peut être écrit à partir d’un nuanceur de vertex ou de géométrie. uint

Limitations lors de l’écriture de SV_Depth :

  • Lorsque l’échantillonnage multiple (MultisampleEnable a la valeur TRUE dans D3D10_RASTERIZER_DESC) et l’écriture d’une valeur de profondeur (à l’aide d’un nuanceur de pixels), la valeur unique écrite est également utilisée dans le test de profondeur. Par conséquent, la possibilité d’afficher les bords primitifs à une résolution supérieure est perdue lors de l’échantillonnage multiple.
  • Lorsque vous utilisez le contrôle de flux dynamique, il est impossible de déterminer au moment de la compilation si un nuanceur qui écrit SV_Depth dans certains chemins d’accès est garanti pour écrire SV_Depth dans chaque exécution. Le fait de ne pas écrire SV_Depth lorsqu’il est déclaré entraîne un comportement indéfini (qui peut ou non inclure l’abandon du pixel).
  • Toute valeur float32, y compris +/-INF et NaN, peut être écrite dans SV_Depth.
  • L’écriture de SV_Depth est toujours valide lors de l’exécution d’une fusion de couleurs double source.

Migration de Direct3D 9 vers Direct3D 10 et versions ultérieures

Les problèmes suivants doivent être pris en compte lors de la migration du code de Direct3D 9 vers Direct3D 10 et versions ultérieures :

Mappage à la sémantique Direct3D 9

Quelques-unes des sémantiques Direct3D 10 et ultérieures mappent directement à la sémantique Direct3D 9.

Sémantique Direct3D 10 Sémantique équivalente Direct3D 9
SV_Depth DEPTH
SV_Position POSITION
SV_Target COULEUR

[!] Remarque pour les développeurs Direct3D 9 : pour les cibles Direct3D 9, la sémantique du nuanceur doit mapper à une sémantique Direct3D 9 valide. Pour la compatibilité descendante, FXC traite POSITION0 (et ses noms de variantes) comme SV_Position. FXC traite COLOR comme SV_TARGET. Les compilateurs DXC et versions plus récentes considèrent POSITION[n] et COLOR comme une sémantique définie par l’utilisateur.

Direct3D 9 VPOS et Direct3D 10 SV_Position

La sémantique D3D10 SV_Position propose des fonctionnalités similaires à la sémantique VPOS 3 du nuanceur Direct3D 9. Par exemple, dans Direct3D 9, la syntaxe suivante est utilisée pour un nuanceur de pixels à l’aide de coordonnées d’espace d’écran :

float4 psMainD3D9( float4 screenSpace : VPOS ) : COLOR
{
    // code here 
}

VPOS a été ajouté pour la prise en charge du modèle de nuanceur 3, afin de spécifier les coordonnées d’espace d’écran, car la sémantique POSITION était destinée aux coordonnées espace-objet.

Dans Direct3D 10 et versions ultérieures, la sémantique SV_Position (lorsqu’elle est utilisée dans le contexte d’un nuanceur de pixels) spécifie les coordonnées d’espace d’écran (décalées de 0,5). Par conséquent, le nuanceur Direct3D 9 serait approximativement équivalent (sans prendre en compte le décalage de 0,5) à ce qui suit :

float4 psMainD3D10( float4 screenSpace : SV_Position ) : COLOR
{
    // code here
}

Lors de la migration de Direct3D 9 vers Direct3D 10 et versions ultérieures, vous devez en savoir plus lors de la conversion de vos nuanceurs.

Plans de découpage utilisateur dans HLSL

À compter de Windows 8, vous pouvez utiliser l’attribut de fonction clipplanes dans une déclaration de fonction HLSL plutôt que SV_ClipDistance pour que votre nuanceur fonctionne au niveau des fonctionnalités 9_x ainsi que le niveau de fonctionnalité 10 et supérieur. Pour plus d’informations, consultez Plans de découpage utilisateur sur le matériel de niveau de fonctionnalité 9.