> ## 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. # XDXRStandaloneTraverse > XDXRStandaloneTraverse XDXR ne prend actuellement pas en charge l'objet `RayQuery` décrit dans DXR 1.1. Cependant, nous fournissons une implémentation de parcours dans un seul en-tête (avec plusieurs variantes) qui partage la majeure partie de notre logique de parcours DXR 1.0 et l'encapsule dans une API largement équivalente à l'API de l'objet `RayQuery`. Cet en-tête peut être utilisé dans n'importe quelle étape de nuanceur qui permet l'allocation de LDS par l'utilisateur, y compris les nuanceurs de calcul et de pixels. Ce système devrait permettre une conversion simple (presque 1:1) du code de rendu PC reposant sur le `RayQuery` de DXR 1.1. De plus, dans les situations comportant un petit nombre de nuanceurs de lancer de rayons (AnyHit/ClosestHit/etc.), ce système est souvent nettement plus rapide que le lancer de rayons de style DXR 1.0 sur XBOX, en raison d'une surcharge moindre. Il est fortement recommandé d'utiliser ce système d'en-tête en ligne pour les fonctionnalités de rendu comme les ombres ou l'occlusion ambiante. Notez que XDXR n'effectue actuellement pas l'intégration en ligne des petites tables de liaison de nuanceurs pour DXR 1.0. Certains IHV PC peuvent avoir des recommandations différentes pour cette raison. Nous recommandons de profiler les compromis du lancer de rayons XBOX indépendamment des pilotes PC. ## Utilisation ### En-têtes À la place de l'objet `RayQuery` de DXR 1.1, nous fournissons plusieurs versions d'un fichier d'en-tête XDXRStandaloneTraverse\*\*\*.hlsli dans le répertoire d'installation du GDK : `GDK_Install_Path\GDK_Version\GXDK\gameKit\Include\Scarlett`. Ces en-têtes sont fournis sous forme de code source; toutefois, il incombe au développeur de s'assurer que la version de son fichier d'en-tête est compatible avec le GDK avec lequel ses BVH sont construits. Les versions antérieures de l'en-tête ne seront pas prises en charge sur les GDK plus récents, et les modifications de l'en-tête doivent être fusionnées avec toute modification provenant d'un GDK plus récent. Actuellement, ces versions sont les suivantes : * XDXRStandaloneTraverseShortStack.hlsli * Cette version du parcours reflète l'algorithme de parcours par défaut actuellement utilisé pour la prise en charge de DXR 1.0 dans XDXR. Recommandée pour tout lancer de rayons susceptible d'être divergent, comme l'AO ou les réflexions brillantes. * XDXRStandaloneTraverseHT.hlsli * Cette version du parcours implémente un algorithme de parcours « cohérent » qui peut être plus rapide que les autres algorithmes pour du contenu très cohérent comme les rayons d'ombre ou les réflexions miroir. Cela équivaut à spécifier `XBOX_RAY_FLAG_COHERENT_RAYS_HINT` dans les indicateurs de rayon de votre `TraceRay()` DXR 1.0. * XDXRStandaloneTraverseShortStackNoMultibox.hlsli * Cette version du parcours ne prend pas en charge les BVH construits hors ligne, mais peut être légèrement plus rapide si seules des constructions de BVH à l'exécution sont effectuées. * XDXRStandaloneTraverseLongStack.hlsli * Cette version du parcours a une taille de pile maximale de 32 nœuds; elle peut être plus rapide sur certains contenus, mais peut entraîner des impacts de rayons manqués. ### Intégration Les en-têtes XDXRStandaloneTraverse fournissent un objet `XboxRayQuery` qui reflète l'objet `RayQuery` de DXR 1.1. Mis à part le nommage, l'API devrait être identique à celle de DXR 1.1, avec les différences suivantes : * Les indicateurs de modèle comme `XboxRayQuery` sont pris en charge uniquement lors de la compilation avec HLSL 2021, dans le GDK de mars 2024 ou ultérieur. * Avant HLSL 2021 et le GDK de mars 2024, à la place de `RayQuery`, les utilisateurs doivent effectuer l'une des opérations suivantes : * Placer tous les indicateurs dans le paramètre rayFlags de TraceRayInline(). Privilégiez les littéraux de compilation pour les indicateurs plutôt que des valeurs de mémoire tampon constante afin de permettre une meilleure génération de code. Envisagez de créer des branches autour de différents appels à TraceRayInline() si vous souhaitez basculer des indicateurs. * À la place de `RayQuery`, utilisez `XboxRayQuery.TraceRayInlineNoAHS()`; de même, utilisez `XboxRayQuery.TraceRayInlineNoIS()` ou `XboxRayQuery.TraceRayInlineNoAHSNoIS()` pour désactiver la gestion des nuanceurs d'intersection. * De façon équivalente, l'objet `XboxRayQuery` comporte les membres booléens `disableAHS` et `disableIS`, qui peuvent être définis sur des littéraux après l'appel à `TraceRayInline`, mais avant le premier appel à `Proceed()`. * `XboxRayQuery` maintient un état global; toute utilisation d'un objet `XboxRayQuery` doit être terminée avant la création ou l'utilisation d'un deuxième objet. Cela inclut l'interrogation de l'état ou des renseignements d'impact final. * XDXR (et `XboxRayQuery`) ne prennent actuellement pas en charge `RAY_FLAG_SKIP_TRIANGLES` ni `RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES`. Si une séparation est nécessaire, envisagez de construire plusieurs TLAS en parallèle avec l'API de générateur par lots. * Une exception est que `XboxRayQuery` est pris en charge dans HLSL2021 et équivaut à `XboxRayQuery.TraceRayInlineNoIS()`. Cet indicateur est pris en charge uniquement en tant que paramètre de modèle. * En raison de la structure de l'algorithme cohérent, `XDXRStandaloneTraverseHT.hlsli` exige que tout le code de gestion de `Proceed()` vérifie qu'un impact valide a bien été signalé en ajoutant un `if (query.CandidateType() == CANDIDATE_NON_OPAQUE_TRIANGLE || query.CandidateType() == CANDIDATE_PROCEDURAL_PRIMITIVE)` avant la logique AnyHit ou de nuanceur d'intersection. Bien que cela soit permis dans DXR 1.1 normal, cette vérification est souvent omise s'il est connu que le BVH ne contient qu'un seul type de primitive. Cela entraînera des artefacts dans l'implémentation `XDXRStandaloneTraverseHT.hlsli`. * L'implémentation de parcours `XDXRStandaloneTraverseHT.hlsli` exige que les indicateurs de rayon et le pointeur de TLAS soient uniformes. * Le parcours autonome XDXR comprend plusieurs extensions absentes de DXR 1.1, abordées dans la section suivante. ### CurrentNumIterations() et SetMaxNumIterations() Le parcours autonome XDXR ajoute deux extensions simples liées à l'interrogation et à la limitation du nombre d'itérations de parcours. Notez que chacune de ces extensions peut entraîner une pression VGPR ou une charge ALU supplémentaire. Les utilisateurs ne devraient pas utiliser ou activer ces fonctionnalités, sauf s'ils ont l'intention de définir une limite d'itérations suffisamment basse pour compenser le coût supplémentaire. * `XboxRayQuery.CurrentNumIterations()` renvoie le nombre d'itérations de la logique de parcours effectuées jusqu'à présent. Cette fonction peut être appelée après le parcours, pour dessiner une carte thermique, ou dans la logique AHS ou similaire pour prendre des décisions. Toute référence à cette fonction dans votre nuanceur ajoute un léger coût au parcours, y compris lorsqu'elle est derrière un indicateur d'exécution. Il est recommandé de placer tout mode « carte thermique » derrière un indicateur `#ifdef` pour s'assurer que les modes de version finale ne sont pas affectés. * `XboxRayQuery.SetMaxNumIterations(uint maxNumIterations)` permet de définir un nombre maximal d'itérations, après lequel le parcours se terminera prématurément, et les résultats incluront l'impact validé le plus récent (ou rien, si aucun n'a encore été trouvé). * Pour utiliser cette fonctionnalité, `#define XDXR_ENABLE_ITERATION_LIMIT 1` doit être défini avant l'inclusion de l'en-tête de parcours. * Placez l'appel à `XboxRayQuery.SetMaxNumIterations(YOUR_ITERATION_LIMIT)` après l'appel à `XboxRayQuery.TraceRayInline()` et avant l'appel à `XboxRayQuery.Proceed()`. * Pour vérifier si le parcours s'est terminé prématurément, vérifiez si `XboxRayQuery.CurrentNumIterations() >= YOUR_ITERATION_LIMIT`. Notez que le nombre d'itérations peut être supérieur à la limite, en particulier dans le cas de `XDXRStandaloneTraverseHT.hlsli`, car certaines étapes du parcours ne peuvent pas être interrompues prématurément sans entraîner un coût important. ### InlineAHS et InlineIS Le parcours autonome XDXR fournit deux extensions pour améliorer la vitesse de parcours lorsqu'une logique AnyHit ou de nuanceur d'intersection simple est requise. Par défaut, le parcours RayQuery de DXR 1.1 doit sortir de la boucle de parcours du BVH afin de donner le contrôle à l'utilisateur pour la gestion de la logique AnyHit ou de nuanceur d'intersection dans une boucle `while(query.Proceed())`. Cela peut entraîner un contrôle de flux complexe et des performances sous-optimales. Le parcours autonome XDXR fournit les mécanismes InlineAHS et InlineIS pour améliorer les performances en permettant d'intégrer en ligne la logique AHS ou IS dans la boucle de parcours. À partir du GDK de mars 2024, les définitions `XDXR_USE_INLINE_AHS_FUNCTION` et `XDXR_USE_INLINE_IS_FUNCTION` sont dépréciées. Les fonctionnalités InlineAHS et InlineIS sont maintenant offertes au moyen d'une API basée sur les modèles HLSL 2021, qui présente plusieurs avantages. Les instructions pour la version HLSL 2021 suivent, avec une section sur la version antérieure ci-dessous. #### InlineAHS et InlineIS en HLSL 2021 * Créez une structure HLSL qui étend `InlineAHSBaseLambda`, `InlineISBaseLambda` ou `InlineAHSAndISBaseLambda`, selon que vous avez besoin d'une logique AnyHit (AHS), d'une logique d'intersection procédurale (IS) ou des deux. * Créez une fonction avec la signature et le nom `void InlineAHS(inout XboxRayQueryProxy rqp)` et/ou `void InlineIS(inout XboxRayQueryProxy rqp)` dans votre structure. * Coupez/collez toute la logique AHS et IS de votre boucle `while(query.Proceed()) {ISLogic(); AHSLogic()}` dans les fonctions `InlineAHS` ou `InlineIS`. * L'objet `XboxRayQueryProxy` prend en charge toutes les mêmes fonctionnalités que l'objet `XboxRayQuery` normal, à l'exception de l'accesseur `XboxRayQuery.CandidateType()`. Gérez la logique `CANDIDATE_NON_OPAQUE_TRIANGLE` dans `InlineAHS()` et la logique `CANDIDATE_PROCEDURAL_PRIMITIVE`, y compris le test alpha, dans `InlineIS()`. * L'objet `XboxRayQueryProxy` peut servir à interroger les renseignements de parcours exactement de la même façon qu'un objet `RayQuery` normal, et à gérer les impacts au moyen des fonctions `rayQueryProxy.CommitNonOpaqueTriangleHit()` ou `rayQueryProxy.Abort()`. * `rayQueryProxy.CandidateProceduralPrimitiveNonOpaque()` peut être interrogé dans `InlineIS()` pour déterminer si la logique AHS doit être effectuée pour la primitive procédurale. C'est la même chose que le lancer de rayons en ligne standard de DXR 1.1. * Lorsque `InlineAHS` ou `InlineIS` (ou les deux) sont utilisés, il n'est pas nécessaire de placer l'appel à `rayQuery.Proceed()` dans une boucle while, car le contrôle ne reviendra pas à l'utilisateur avant la fin du parcours. Toute la logique AHS ou IS sera intégrée en ligne au moyen des fonctions fournies. ```cpp theme={null} #ifdef COMPILE_FLAG_INLINE_TRAVERSAL_HYBRID #include "XDXRStandaloneTraverseHT.hlsli" #else #include "XDXRStandaloneTraverseShortStack.hlsli" #endif // Extend one of: InlineAHSBaseLambda, InlineISBaseLambda, InlineAHSAndISBaseLambda. // Implement one or both of: void InlineAHS(inout XboxRayQueryProxy rqp), void InlineIS(inout XboxRayQueryProxy rqp). struct MyAHSLambda : InlineAHSBaseLambda { // Optional: lambda structs can contain whatever state is required for your use-case. bool statefulVariable; void InlineAHS(inout XboxRayQueryProxy rqp) { if (MyAnyHitShaderImpl(...)) { // rqp is inout, use the Commit functions as you would in DXR 1.1. rqp.CommitNonOpaqueTriangleHit(); } if (statefulVariable) { ... } // Default is to ignore hits, to exit traversal completely use rqp.Abort(). } }; // Requires HLSL 2021. [RootSignature(GlobalRootSignature)] [numthreads(8, 4, 1)] void MyRaygenShaderWith2021Lambda(uint3 DTid : SV_DispatchThreadID) { RayDesc myRay = { ... }; // RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES is used here to avoid costs associated with procedural primitive handling. // MyAHSLambda's InlineAHS will be inlined into the traversal loop. XboxRayQuery xrq; xrq.TraceRayInline( Scene, RAY_FLAG_NONE, 0xff, myRay); MyAHSLambda myStatefulLambda; myStatefulLambda.statefulVariable = bool(DTid.x < 10); // Looping over this call is not required if the InlineAHS mechanism is used. // If your lambda struct has state members, it must be instantiated and provided as an argument to Proceed(). // If your lambda struct does not have state members, this parameter can be omitted. xrq.Proceed(/*optional*/ myStatefulLambda); if (xrq.CommittedStatus() == COMMITTED_TRIANGLE_HIT) { ... } } // Requires HLSL 2021. [RootSignature(GlobalRootSignature)] [numthreads(8, 4, 1)] void MyRaygenShaderWith2021Flags(uint3 DTid : SV_DispatchThreadID) { RayDesc myRay = { ... }; // RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES is used here to avoid costs associated with procedural primitive handling. XboxRayQuery xrq; xrq.TraceRayInline( Scene, RAY_FLAG_NONE, 0xff, myRay); // We have to loop over hit-candidates here. Normal DXR 1.1 Inline Raytracing style. while (xrq.Proceed()) { // This if-statement is required for XDXRStandaloneTraverseHT even if the BVH is known to only contain triangles. Otherwise lanes without hits may remain active in this loop. if (xrq.CandidateType() == CANDIDATE_NON_OPAQUE_TRIANGLE) { if (MyAnyHitShaderImpl(alphaTexture, shaderRecord.alphaIsMask, xrq.CandidateTriangleBarycentrics(), u1, u2, u3)) { xrq.CommitNonOpaqueTriangleHit(); } } } if (xrq.CommittedStatus() == COMMITTED_TRIANGLE_HIT) { ... } } // Works in HLSL 2018. [RootSignature(GlobalRootSignature)] [numthreads(8, 4, 1)] void MyRaygenShaderWith2018Flags(uint3 DTid : SV_DispatchThreadID) { RayDesc myRay = { ... }; // No template flags in HLSL 2018. XboxRayQuery xrq; // TraceRayInlineNoIS is used here to avoid costs associated with procedural primitive handling. // Equivalent to XboxRayQuery in HLSL 2021 versions. xrq.TraceRayInlineNoIS( Scene, RAY_FLAG_NONE, 0xff, myRay); while (xrq.Proceed()) { // This if-statement is required for XDXRStandaloneTraverseHT even if the BVH is known to only contain triangles. Otherwise lanes without hits may remain active in this loop. if (xrq.CandidateType() == CANDIDATE_NON_OPAQUE_TRIANGLE) { if (MyAnyHitShaderImpl(alphaTexture, shaderRecord.alphaIsMask, xrq.CandidateTriangleBarycentrics(), u1, u2, u3)) { xrq.CommitNonOpaqueTriangleHit(); } } } if (xrq.CommittedStatus() == COMMITTED_TRIANGLE_HIT) { ... } } ``` #### InlineAHS et InlineIS en HLSL 2018 (déprécié) * Spécifiez `#define XDXR_USE_INLINE_AHS_FUNCTION 1` et/ou `#define XDXR_USE_INLINE_IS_FUNCTION 1` avant `#include "XDXRStandaloneTraverse****.hlsli"`. Notez que si la logique AHS et la logique IS sont toutes deux présentes, elles doivent toutes deux utiliser le système Inline et ne peuvent pas être combinées avec les gestionnaires DXR 1.1 normaux. * Créez une fonction globale avec la signature et le nom `void InlineAHS(inout XboxRayQueryProxy rqp)` et/ou `void InlineIS(inout XboxRayQueryProxy rqp)` * Suivez les instructions de la version HLSL 2021 ci-dessus, en remplaçant les fonctions membres InlineAHS et InlineIS de la structure par les fonctions InlineAHS et InlineIS définies globalement. ## Mémoire Le pilote XDXR alloue de la mémoire de stockage pour le parcours de style `TraceRay()` de DXR 1.0. Si votre titre utilise uniquement le lancer de rayons en ligne, vous pourriez vouloir récupérer cette mémoire. En date de juin 2022, il s'agit de 12 Mo sur XBOX Series S et de 32 Mo sur XBOX Series X. Pour désactiver cette mémoire, un titre doit spécifier `D3D12_GPU_VIRTUAL_ADDRESS_UNKNOWN` pour `pDXRStackBuffer` et spécifier une taille de `0` pour `DXRStackBufferOverrideSizeBytes` dans [D3D12XBOX\_CREATE\_DEVICE\_PARAMETERS](/fr-CA/reference/graphics/d3d12_xs/structs/d3d12xbox_create_device_parameters_xs). ## Intégration à PIX Consultez la section « Draw Rays » de la documentation de la [visionneuse de BVH de PIX](/fr-CA/tools/tools-console/pix/gpu/pix-bvh-viewer) pour obtenir des instructions sur l'activation de l'affichage des trajectoires de rayons et de la carte thermique dans PIX lors de l'utilisation du parcours autonome. ## Voir aussi [Visionneuse de BVH de PIX](/fr-CA/tools/tools-console/pix/gpu/pix-bvh-viewer) [Vue d'ensemble du lancer de rayons (et de DXR)](/fr-CA/build/core-features/graphics/newfeatures/raytracing/rt-overview) ## Related topics - [XDXR を使用した XBOX Series X|S でのレイ トレーシング](/ja-jp/build/core-features/graphics/newfeatures/raytracing/index.md) - [NDA topic directory - live Microsoft Learn links](/nda/nda-topic-directory.md) - [Diretório de tópicos NDA: links ativos do Microsoft Learn](/pt-BR/nda/nda-topic-directory.md) - [Directorio de temas NDA: enlaces activos a Microsoft Learn](/es/nda/nda-topic-directory.md) - [Répertoire des rubriques NDA : liens actifs vers Microsoft Learn](/fr/nda/nda-topic-directory.md)