> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SetSamplePositions

> Cette méthode configure les positions d'échantillons utilisées par les opérations ultérieures de dessin, de copie, de résolution et similaires.

Cette méthode configure les positions d'échantillons utilisées par les opérations ultérieures de dessin, de copie, de résolution et similaires.

## Syntaxe

```cpp theme={null}
void SetSamplePositions(
    UINT NumSamplesPerPixel,
    UINT NumPixels,
    D3D12_SAMPLE_POSITION  pSamplePositions
)
```

### Paramètres

*NumSamplesPerPixel \[in]*\
Type : UINT

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values) : <code>*In*</code>

Spécifie le nombre d'échantillons à prélever par pixel. Cette valeur peut être 1, 2, 4, 8 ou 16 ; sinon, l'appel à SetSamplePosition est ignoré. Le nombre d'échantillons doit correspondre au nombre d'échantillons configuré dans le PSO au moment du dessin ; sinon, le comportement est indéfini.

*NumPixels \[in]*\
Type : UINT

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values) : <code>*In*</code>

Spécifie le nombre de pixels pour lesquels des modèles d'échantillonnage sont spécifiés. Cette valeur peut être 1 ou 4 ; sinon, l'appel à SetSamplePosition est ignoré. Une valeur de 1 configure un modèle d'échantillonnage unique à utiliser pour chaque pixel ; une valeur de 4 configure des modèles d'échantillonnage distincts pour chaque pixel d'une grille de 2x2 pixels qui est répétée sur l'espace de la cible de rendu ou de la fenêtre d'affichage, alignée sur des coordonnées paires.

Notez que le nombre maximal d'échantillons combinés ne peut pas dépasser 16 ; sinon, l'appel est ignoré. Si NumPixels est défini sur 4, NumSamplesPerPixel ne peut pas spécifier plus de 4 échantillons.

*pSamplePositions \[in]*\
Type : D3D12\_SAMPLE\_POSITION \*

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values) : <code>*In\_reads*(NumSamplesPerPixel\*NumPixels)</code>

Spécifie un tableau d'éléments D3D12\_SAMPLE\_POSITION. La taille du tableau est NumPixels \* NumSamplesPerPixel. Si NumPixels est défini sur 4, le premier groupe de positions d'échantillons correspond au pixel supérieur gauche de la grille de 2x2 pixels ; le groupe suivant correspond au pixel supérieur droit, le suivant au pixel inférieur gauche et le dernier au pixel inférieur droit.

Si l'interpolation centroïde est utilisée pendant le rendu, l'ordre des positions de chaque pixel détermine la priorité de l'échantillonnage centroïde. Autrement dit, le premier échantillon couvert dans l'ordre spécifié est choisi comme emplacement d'échantillon centroïde.

### Valeur renvoyée

Type : void

Aucune.

## Remarques

La sémantique opérationnelle des positions d'échantillons est déterminée par les différentes opérations de dessin, de copie, de résolution et autres qui peuvent se produire.

**CommandList :** en l'absence d'appels antérieurs à SetSamplePositions dans une CommandList, les échantillons prennent la position par défaut basée sur le PSO (Pipeline State Object). Les positions par défaut sont déterminées soit par la partie SAMPLE\_DESC du PSO si elle est présente, soit par les positions d'échantillons standard si la partie RASTERIZER\_DESC du PSO a ForcedSampleCount défini sur une valeur supérieure à 0.

Une fois SetSamplePosition appelée, les appels de dessin suivants doivent utiliser un PSO qui spécifie un nombre d'échantillons correspondant, soit à l'aide de la partie SAMPLE\_DESC du PSO, soit à l'aide de ForcedSampleCount dans la partie RASTERIZER\_DESC du PSO.

SetSamplePositions ne peut être appelée que sur une CommandList graphique. Elle ne peut pas être appelée dans un bundle ; les bundles héritent de l'état des positions d'échantillons de la CommandList appelante et ne le modifient pas.

L'appel de SetSamplePositions(0, 0, NULL) rétablit les valeurs par défaut des positions d'échantillons.

**Effacement d'une RenderTarget :** les positions d'échantillons sont ignorées lors de l'effacement d'une cible de rendu.

**Effacement d'un DepthStencil :** lors de l'effacement de la partie profondeur d'une surface de profondeur-gabarit ou de toute région de celle-ci, les positions d'échantillons doivent être définies pour correspondre à celles du futur rendu vers la surface ou la région effacée ; le contenu des régions non effacées produites à l'aide de positions d'échantillons différentes devient indéfini.

Lors de l'effacement de la partie gabarit d'une surface de profondeur-gabarit ou de toute région de celle-ci, les positions d'échantillons sont ignorées.

**Dessin vers une RenderTarget :** lors du dessin vers une cible de rendu, les positions d'échantillons peuvent être modifiées pour chaque appel de dessin, même lors du dessin vers une région qui chevauche des appels de dessin précédents. Les positions d'échantillons actuelles déterminent la sémantique opérationnelle de chaque appel de dessin, et les échantillons sont prélevés à partir du contenu stocké de la cible de rendu, même si ce contenu a été produit à l'aide de positions d'échantillons différentes.

**Dessin à l'aide d'un DepthStencil :** lors du dessin vers une surface de profondeur-gabarit (en lecture ou en écriture) ou toute région de celle-ci, les positions d'échantillons doivent être définies pour correspondre à celles utilisées précédemment pour effacer la région concernée. Pour utiliser une position d'échantillon différente, la région cible doit d'abord être effacée. Les pixels situés en dehors de la région effacée ne sont pas affectés.

Le matériel peut stocker la partie profondeur d'une surface de profondeur-gabarit sous forme d'équations de plan, et les évaluer pour produire des valeurs de profondeur lorsque l'application émet une lecture. Seuls le rastériseur et la fusion de sortie (output-merger) sont tenus de prendre en charge les positions d'échantillons programmables de la partie profondeur d'une surface de profondeur-gabarit. Toute autre lecture ou écriture de la partie profondeur rendue avec des positions d'échantillons définies peut les ignorer et échantillonner aux positions standard.

**Résolution d'une RenderTarget :** lors de la résolution d'une cible de rendu ou de toute région de celle-ci, les positions d'échantillons sont ignorées ; ces API opèrent uniquement sur les valeurs de couleur stockées.

**Résolution d'un DepthStencil :** lors de la résolution de la partie profondeur d'une surface de profondeur-gabarit ou de toute région de celle-ci, les positions d'échantillons doivent être définies pour correspondre à celles du rendu passé vers la surface ou la région résolue. Pour utiliser une position d'échantillon différente, la région cible doit d'abord être effacée.

Lors de la résolution de la partie gabarit d'une surface de profondeur-gabarit ou de toute région de celle-ci, les positions d'échantillons sont ignorées ; les résolutions de gabarit opèrent uniquement sur les valeurs de gabarit stockées.

**Copie d'une RenderTarget :** lors d'une copie à partir d'une cible de rendu, les positions d'échantillons sont ignorées, qu'il s'agisse d'une copie complète ou partielle.

**Copie d'un DepthStencil (sous-ressource complète) :** lors de la copie d'une sous-ressource complète à partir d'une surface de profondeur-gabarit, les positions d'échantillons doivent être définies pour correspondre aux positions d'échantillons utilisées pour générer la surface source. Pour utiliser une position d'échantillon différente, la région cible doit d'abord être effacée.

Sur certains matériels, des propriétés de la surface source (telles que les équations de plan stockées pour les valeurs de profondeur) sont transférées vers la destination. Par conséquent, si la surface de destination fait ensuite l'objet d'un dessin, les positions d'échantillons utilisées à l'origine pour générer le contenu source doivent être utilisées avec la surface de destination. L'API l'exige sur tous les matériels par souci de cohérence, même si cela ne s'applique qu'à certains.

**Copie d'un DepthStencil (sous-ressource partielle) :** lors de la copie d'une sous-ressource partielle à partir d'une surface de profondeur-gabarit, les positions d'échantillons doivent être définies pour correspondre aux positions d'échantillons utilisées pour générer la surface source, comme pour la copie d'une sous-ressource complète. Toutefois, si le contenu des sous-ressources de destination concernées n'est que partiellement couvert par la copie, le contenu de la partie non couverte de ces sous-ressources devient indéfini, sauf s'il a été entièrement généré à l'aide des mêmes positions d'échantillons que la source de la copie. Pour utiliser une position d'échantillon différente, la région cible doit d'abord être effacée.

Lors de la copie d'une sous-ressource partielle à partir de la partie gabarit d'une surface de profondeur-gabarit, les positions d'échantillons sont ignorées. Les positions d'échantillons utilisées pour générer le contenu des autres zones de la mémoire tampon de destination non couvertes par la copie n'ont pas d'importance : ce contenu reste valide.

**SamplePos de nuanceur :** la fonction intrinsèque HLSL SamplePos n'a pas connaissance des positions d'échantillons programmables, et les résultats renvoyés aux nuanceurs qui l'appellent sur une surface rendue avec des positions programmables sont indéfinis. Les applications doivent transmettre manuellement les coordonnées à leur nuanceur si nécessaire. De même, l'évaluation des attributs par index d'échantillon est indéfinie avec des positions d'échantillons programmables.

**Transition hors de l'état DEPTH\_READ ou DEPTH\_WRITE :** si une sous-ressource à l'état DEPTH\_READ ou DEPTH\_WRITE passe à un autre état, y compris COPY\_SOURCE ou RESOLVE\_SOURCE, certains matériels peuvent avoir besoin de décompresser la surface. Par conséquent, les positions d'échantillons doivent être définies sur la liste de commandes pour correspondre à celles utilisées pour générer le contenu de la surface source. En outre, pour toutes les transitions ultérieures de la surface tant qu'elle contient les mêmes données de profondeur, les positions d'échantillons doivent continuer à correspondre à celles définies sur la liste de commandes. Pour utiliser une position d'échantillon différente, la région cible doit d'abord être effacée.

Si une application souhaite réduire la zone décompressée lorsque seule une partie doit être utilisée, ou simplement préserver la compression, ResolveSubresourceRegion() peut être appelée en mode DECOMPRESS avec un rectangle spécifié.  Cela décompresse uniquement la zone concernée dans une ressource distincte en laissant la source intacte sur certains matériels, alors que sur d'autres matériels, même la zone source est décompressée. La ressource distincte explicitement décompressée peut ensuite passer à l'état souhaité (tel que SHADER\_RESOURCE).

**Transition hors de l'état RENDER\_TARGET :** si une sous-ressource à l'état RENDER\_TARGET passe à un état autre que COPY\_SOURCE ou RESOLVE\_SOURCE, certaines implémentations peuvent avoir besoin de décompresser la surface. Cette décompression est indépendante des positions d'échantillons.

Si une application souhaite réduire la zone décompressée lorsque seule une partie doit être utilisée, ou simplement préserver la compression, ResolveSubresourceRegion() peut être appelée en mode DECOMPRESS avec un rectangle spécifié.  Cela décompresse uniquement la zone concernée dans une ressource distincte en laissant la source intacte sur certains matériels, alors que sur d'autres matériels, même la zone source est décompressée. La ressource distincte explicitement décompressée peut ensuite passer à l'état souhaité (tel que SHADER\_RESOURCE).

## Configuration requise

**En-tête :** d3d12\_xs.h ou d3d12\_x.h\
**Bibliothèque :** d3d12\_xs.lib ou d3d12\_x.lib\
**Plateformes prises en charge** : consoles XBOX Series et famille XBOX One

## Voir aussi

[ID3D12GraphicsCommandList1](/fr/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist1/id3d12graphicscommandlist1_public)


## Related topics

- [D3D12_PROGRAMMABLE_SAMPLE_POSITIONS_TIER](/fr/reference/graphics/d3d12/enums/d3d12_programmable_sample_positions_tier_public.md)
- [GetXmaDecodePositionForSample](/fr/reference/audio/xma2defs/functions/getxmadecodepositionforsample.md)
- [D3D12_SAMPLE_POSITION](/fr/reference/graphics/d3d12/structs/d3d12_sample_position_public.md)
- [XSpeechToTextSetPositionHint](/fr/reference/system/xaccessibility/functions/xspeechtotextsetpositionhint.md)
- [GetXmaBlockContainingSample](/fr/reference/audio/xma2defs/functions/getxmablockcontainingsample.md)