Sémantique

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 sur toutes les variables passées entre les étapes 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, 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émantiques de valeur système.

Sémantique prise en charge dans Direct3D 9 et Direct3D 10 et versions ultérieures

Les types de sémantiques 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.

Entrée Description Type
BINORMAL[n] Binormal float4
BLENDINDICES[n] Index blend uint
BLENDWEIGHT[n] Poids de fusion 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 du point float
TANGENT[n] Tangente float4
TEXCOORD[n] Coordonnées de texture float4
Output Description Type
COLOR[n] Couleur diffuse ou spéculaire float4
BROUILLARD 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. float4
PSIZE Taille du point float
TESSFACTOR[n] Facteur de pavage 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.

Entrée Description Type
COLOR[n] Couleur spéculaire ou diffuse. float4
TEXCOORD[n] Coordonnées de texture float4
VFACE Scalaire à virgule flottante qui indique une primitive orientée arrière. Une valeur négative fait face à l’arrière, tandis qu’une valeur positive fait face à la caméra.
[! Remarque]
Cette sémantique est disponible dans direct3D 9 Shader Model 3.0. Pour Direct3D 10 et versions ultérieures, utilisez plutôt SV_IsFrontFace .

float
VPOS Emplacement du pixel (x,y) dans l’espace de l’écran. Pour convertir un nuanceur Direct3D 9 (qui utilise cette sémantique) en nuanceur Direct3D 10 et ultérieur, voir Direct3D 9 VPOS et Direct3D 10 SV_Position) float2
Output 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émantiques suivants ont été récemment introduits pour Direct3D 10 et ne sont pas disponibles pour Direct3D 9.

Sémantique System-Value

La sémantique de valeur système est nouvelle pour Direct3D 10. Toutes les valeurs système commencent par un préfixe SV_, un exemple courant est SV_POSITION, qui est interprété par l’étape de 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 dans un nuanceur de vertex ainsi qu’une sortie. Les nuanceurs de pixels peuvent uniquement écrire dans des paramètres avec la sémantique SV_Depth et SV_Target de valeur système.

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; après cela, la fonction de nuanceur doit passer les valeurs aux étapes suivantes.

SV_PrimitiveID est une exception à cette règle d’entrée uniquement 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 que l’entrée à l’étape du nuanceur de coque, à l’étape du nuanceur de domaine, et après cette étape est activée pour la première fois : phase geometry-shader ou étape de nuanceur de pixels.

Si le pavage est activé, l’étape du 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 patch et à tous les appels de nuanceur de domaine tessellés. Le même PrimitiveID se propage également à l’étape active suivante ; étape geometry-shader ou étape de nuanceur de pixels si elle est activée.

Si le nuanceur géométrique entre SV_PrimitiveID et qu’il peut générer zéro ou une ou plusieurs primitives par appel, le nuanceur doit programmer son propre choix de valeur de SV_PrimitiveID pour chaque primitive de sortie si une entrée de nuanceur de pixels ultérieure SV_PrimtiveID.

Par exemple, SV_PrimitiveID ne peut pas être interprété par l’étape du nuanceur de vertex, car un vertex peut être membre de plusieurs primitives.

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

Sémantique de valeur système pour l’étape de rastériseur.

sémantique System-Value Description Type
SV_ClipDistance[n] Découper les données de distance. SV_ClipDistance valeurs sont supposées être une distance signée float32 à un plan. La configuration primitive appelle uniquement la rastérisation sur les pixels pour lesquels la ou les distances de plan interpolées sont >= 0. Plusieurs plans clip 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 coupure sont au plus des composants D3D#_CLIP_OR_CULL_DISTANCE_COUNT dans la plupart des registres D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT. Disponible pour tous les nuanceurs à lire ou à écrire, à l’exception du nuanceur de vertex qui peut écrire la valeur, mais pas la prendre comme entrée.
L’attribut clipplanes fonctionne comme SV_ClipDistance, mais fonctionne sur tous les niveaux de fonctionnalité matérielle 9_x et versions ultérieures. Pour plus d’informations, consultez les plans de découpage utilisateur sur le matériel de niveau 9 des fonctionnalités.
float
SV_CullDistance[n] Données de distance de coupure. Lorsque les composants des éléments de vertex reçoivent cette étiquette, ces valeurs sont supposées être une distance signée float32 à un plan. Les primitives sont complètement ignorées si la ou les distances de plan pour tous les sommets de la primitive sont < 0. Plusieurs plans de coupure 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 coupure sont au plus des composants D3D#_CLIP_OR_CULL_DISTANCE_COUNT dans la plupart des registres D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT. Disponible pour tous les nuanceurs à lire ou à écrire, à l’exception du nuanceur de vertex qui peut écrire la valeur, mais pas la prendre comme 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 une version ultérieure.
Pour SV_Coverage sur un nuanceur de pixels, INPUT nécessite ps_5_0 ou une version ultérieure.
uint
SV_Depth Données de mémoire tampon de profondeur. Peut être écrit par 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 ratériseur. Active l’ajustement de la profondeur sans désactiver le Z précoce. float
SV_DepthLessEqual Dans un nuanceur de pixels, permet de mettre la profondeur, tant qu’elle est inférieure ou égale à la valeur déterminée par le rasterizer. Active l’ajustement de la profondeur sans désactiver le Z précoce. float
SV_DispatchThreadID Définit le décalage de thread global au sein de l’appel Dispatch, par dimension du groupe. Disponible en tant qu’entrée pour le nuanceur de calcul. (lecture seule) uint3
SV_DomainLocation Définit l’emplacement sur la coque du point de domaine actuel évalué. Disponible en tant qu’entrée au nuanceur de domaine. (lecture seule) float2|3
SV_GroupID Définit le décalage de groupe au sein d’un appel Dispatch, par dimension de l’appel de distribution. Disponible en tant qu’entrée au 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 au nuanceur de calcul. (lecture seule) uint
SV_GroupThreadID Définit le décalage de thread au sein du groupe, par dimension du groupe. Disponible en tant qu’entrée au nuanceur de calcul. (lecture seule) uint3
SV_GSInstanceID Définit l’instance du nuanceur geometry. Disponible en tant qu’entrée au nuanceur géométrique. L’instance est nécessaire en tant que nuanceur géométrique pouvant être appelé jusqu’à 32 fois sur la même primitive géométrique. uint
SV_InnerCoverage Représente les informations de rastérisation conservatrice sous-estimées (c’est-à-dire si un pixel est garanti à être entièrement couvert). Peut être lu ou écrit par le nuanceur de pixels.
SV_InsideTessFactor Définit la quantité de téssellation dans une surface corrective. Disponible dans le nuanceur de coque pour l’écriture et disponible 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 de valeurs System-Generated (Direct3D 10)). Disponible pour tous les nuanceurs.
SV_IsFrontFace Spécifie si un triangle est face à l’avant. Pour les lignes et les points, IsFrontFace a la valeur true. L’exception est tracée en triangles (mode wireframe), ce qui définit IsFrontFace de la même façon que la ratérisation du triangle en mode solide. Peut être écrit par le nuanceur géométrique et lu par le nuanceur de pixels. bool
SV_OutputControlPointID Définit l’index de l’ID du point de contrôle en cours d’exploitation par un appel du point d’entrée principal du nuanceur de coque. Peut être lu par le nuanceur de coque uniquement. uint
SV_Position Lorsque SV_Position est déclaré pour l’entrée dans un nuanceur, il peut avoir l’un des deux modes d’interpolation spécifiés : linearNoPerspective ou linearNoPerspectiveCentroid, où ce dernier entraîne la mise à disposition de valeurs xyz codées par centroïde lors de l’antialiasing multisample. Lorsqu’il est utilisé dans un nuanceur, SV_Position décrit l’emplacement des pixels. Disponible dans tous les nuanceurs pour obtenir le centre de pixels avec un décalage de 0,5. float4
SV_PrimitiveID Identificateur par primitive généré automatiquement par le runtime (voir Utilisation de valeurs System-Generated (Direct3D 10)). Peut être écrit par les nuanceurs geometry ou pixels, et lu par la géométrie, le pixel, la coque ou les nuanceurs de domaine. uint
SV_RenderTargetArrayIndex Index de tableau de cible de rendu. Appliqué à la sortie du nuanceur géométrique et indique la tranche de 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 sommet principal est utilisée. Cette valeur indique également quelle tranche de tableau d’une vue profondeur/gabarit est utilisée à des fins de lecture/écriture.
Peut être écrit à partir du nuanceur géométrique et lu par le nuanceur de pixels.
Si D3D11_FEATURE_DATA_D3D11_OPTIONS3::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer est true, SV_RenderTargetArrayIndex est appliqué à n’importe quel nuanceur qui alimente le rasterizer.
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 par le nuanceur de pixels uniquement. uint
SV_Target[n], où 0 <= n <= 7 Valeur de sortie qui sera stockée dans une cible de rendu. L’index indique les cibles de rendu liées à 8 à écrire. La valeur est disponible pour tous les nuanceurs. float[2|3|4]
SV_TessFactor Définit la quantité de téssellation sur chaque bord d’un correctif. Disponible pour écrire dans le nuanceur de coque et lire dans le nuanceur de domaine. float[2|3|4]
SV_VertexID Identificateur par vertex généré automatiquement par le runtime (voir Utilisation de valeurs System-Generated (Direct3D 10)). Disponible uniquement en tant qu’entrée du nuanceur de vertex. uint
SV_ViewportArrayIndex Index du tableau de fenêtres d’affichage. Appliqué à la sortie du nuanceur géométrique 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 sa transmission au rasterizer. Cette sémantique s’applique uniquement aux primitives ; si une primitive a plusieurs vertex, la valeur du sommet principal est utilisée.
Si D3D11_FEATURE_DATA_D3D11_OPTIONS3::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer est true, SV_ViewportArrayIndex est appliqué à n’importe quel nuanceur qui alimente le rasterizer.
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 les appareils de niveau de débit de shading variable 2 ou ultérieur. 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 le multisamplage (MultisampleEnable est VRAI 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 ; ainsi, la possibilité d’afficher les bords primitifs à une résolution plus élevée est perdue lors de l’échantillonnage multiple.
  • Lors de l’utilisation du 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 sera garanti pour écrire SV_Depth dans chaque exécution. Échec d’écriture SV_Depth lorsqu’une déclaration entraîne un comportement non défini (qui peut ou non inclure l’abandon du pixel).
  • Toute valeur float32 incluant +/-INF et NaN peut être écrite dans SV_Depth.
  • L’écriture de SV_Depth est toujours valide lors de l’exécution d’un mélange 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 sont mappées 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 être mappée à la sémantique Direct3D 9 valide. Pour la compatibilité descendante POSITION0 (et ses noms de variantes) est traité comme SV_Position, COLOR est traité comme SV_TARGET.

Direct3D 9 VPOS et Direct3D 10 SV_Position

La sémantique D3D10 SV_Position fournit des fonctionnalités similaires à la sémantique direct3D 9 nuanceur 3 VPOS. Par exemple, dans Direct3D 9, la syntaxe suivante est utilisée pour un nuanceur de pixels à l’aide des 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, pour spécifier les coordonnées d’espace d’écran, car la sémantique POSITION était destinée aux coordonnées d’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 (offset par 0,5). Par conséquent, le nuanceur Direct3D 9 est à peu près équivalent (sans avoir à 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 être conscient de cela lors de la traduction de vos nuanceurs.

Plans de clip utilisateur dans HLSL

À partir 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 Les plans de clip utilisateur sur le matériel de niveau 9 de la fonctionnalité.