> ## 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 en-tête unique (avec plusieurs variantes) qui partage l'essentiel 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 shader permettant l'allocation de LDS par l'utilisateur, y compris les shaders 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. En outre, dans les situations comportant un petit nombre de shaders de raytracing (AnyHit/ClosestHit/etc.), ce système est souvent nettement plus rapide que le raytracing 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 inline pour les fonctionnalités de rendu telles que les ombres ou l'occlusion ambiante. Notez que XDXR n'effectue actuellement pas l'inlining des petites tables de liaison de shaders (shader-binding-tables) pour DXR 1.0. Certains IHV PC peuvent avoir des recommandations différentes pour cette raison. Nous recommandons de profiler les compromis du raytracing 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 les changements apportés par 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 raytracing 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. Hormis le nommage, l'API devrait être identique à celle de DXR 1.1, avec les différences suivantes : * Les indicateurs de modèle tels que `XboxRayQuery` ne sont pris en charge que lors de la compilation avec HLSL 2021, dans le GDK de mars 2024 ou version ultérieure. * Avant HLSL 2021 et le GDK de mars 2024, à la place de `RayQuery`, les utilisateurs doivent procéder de l'une des manières suivantes : * Placer tous les indicateurs dans le paramètre rayFlags de TraceRayInline(). Préférez des littéraux de compilation pour les indicateurs plutôt que des valeurs de constant buffer 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 Intersection Shaders. * De manière équivalente, il existe les membres booléens `disableAHS` et `disableIS` sur l'objet `XboxRayQuery`, 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 second objet. Cela inclut l'interrogation de l'état ou des informations de l'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 requise, envisagez de construire plusieurs TLAS en parallèle avec l'API de construction par lots. * Une exception : `XboxRayQuery` est pris en charge en HLSL2021 et équivaut à `XboxRayQuery.TraceRayInlineNoIS()`. Cet indicateur n'est pris en charge qu'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 Intersection Shader. Bien que cela soit autorisé dans DXR 1.1 standard, cette vérification est souvent omise lorsqu'on sait que le BVH ne contient qu'un seul type de primitive. Cela provoquera 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 inclut plusieurs extensions absentes de DXR 1.1, décrites dans la section suivante. ### CurrentNumIterations() et SetMaxNumIterations() Le parcours autonome XDXR ajoute deux extensions simples permettant d'interroger et de limiter le 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 à moins de prévoir 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 shader ajoute un léger coût au parcours, y compris lorsqu'elle est placée derrière un indicateur d'exécution. Nous recommandons de placer tous les modes « carte thermique » derrière un indicateur `#ifdef` afin de garantir 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 au-delà duquel le parcours s'interrompt prématurément ; les résultats incluent alors 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 d'inclure 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 interrompu 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 sans entraîner un coût important. ### InlineAHS et InlineIS Le parcours autonome XDXR fournit deux extensions permettant d'améliorer la vitesse de parcours lorsqu'une logique AnyHit ou Intersection Shader simple est requise. Par défaut, le parcours RayQuery de DXR 1.1 doit sortir de la boucle de parcours du BVH afin de rendre le contrôle à l'utilisateur pour la gestion de la logique AnyHit ou Intersection Shader dans une boucle `while(query.Proceed())`. Cela peut entraîner un flux de contrôle complexe et des performances sous-optimales. Le parcours autonome XDXR fournit les mécanismes InlineAHS et InlineIS pour améliorer les performances en permettant l'inlining de la logique AHS ou IS dans la boucle de parcours. Depuis le 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 désormais disponibles via une API HLSL 2021 basée sur des modèles, qui présente plusieurs avantages. Les instructions pour la version HLSL 2021 suivent, avec une section sur la version précédente 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 dans votre structure une fonction dont la signature et le nom sont `void InlineAHS(inout XboxRayQueryProxy rqp)` et/ou `void InlineIS(inout XboxRayQueryProxy rqp)`. * 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 fonctionnalités de 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()`. * Le `XboxRayQueryProxy` peut être utilisé pour interroger les informations de parcours exactement de la même manière qu'un objet `RayQuery` normal, et pour gérer les impacts via les fonctions `rayQueryProxy.CommitNonOpaqueTriangleHit()` ou `rayQueryProxy.Abort()`. * `rayQueryProxy.CandidateProceduralPrimitiveNonOpaque()` peut être interrogé dans `InlineIS()` pour déterminer si la logique AHS doit être exécutée pour la primitive procédurale. C'est identique au raytracing inline 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 à l'utilisateur qu'une fois le parcours terminé. Toute la logique AHS ou IS sera intégrée en ligne à l'aide 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 une logique AHS et une logique IS sont toutes deux présentes, elles doivent toutes deux utiliser le système Inline et ne peuvent pas être combinées avec des gestionnaires DXR 1.1 normaux. * Créez une fonction globale dont la signature et le nom sont `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 support pour le parcours de style `TraceRay()` de DXR 1.0. Si votre titre utilise uniquement le raytracing inline, vous pouvez souhaiter récupérer cette mémoire. Depuis juin 2022, elle représente 12 Mo sur XBOX Series S et 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/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 PIX](/fr/tools/tools-console/pix/gpu/pix-bvh-viewer) pour savoir comment activer l'affichage des trajets de rayons et de la carte thermique dans PIX lors de l'utilisation du parcours autonome. ## Voir aussi [Visionneuse de BVH PIX](/fr/tools/tools-console/pix/gpu/pix-bvh-viewer) [Vue d'ensemble du raytracing (et de DXR)](/fr/build/core-features/graphics/newfeatures/raytracing/rt-overview) ## Related topics - [Répertoire des rubriques NDA : liens actifs vers Microsoft Learn](/fr/nda/nda-topic-directory.md) - [SetShapeFiltVolCommand](/fr/reference/audio/shapeflowgraph/functions/setshapefiltvolcommand.md) - [Vue d'ensemble des SDK autonomes](/fr/services/playfab/sdks/sdk-overview.md) - [Configuration HTTP](/fr/services/playfab/sdks/c/http-config.md) - [SDK PlayFab](/fr/services/playfab/sdks/playfab-sdk-intro.md)