XDXRStandaloneTraverse

​

Utilisation

​

En-têtes

• 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 indicateurs de modèle tels que XboxRayQuery<RAY_FLAG_FORCE_OPAQUE | RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES> 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<RAY_FLAG_XXX | RAY_FLAG_YYY>, 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<RAY_FLAG_FORCE_OPAQUE>, 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<RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES> 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()

• 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

​

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.

#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<RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES, MyAHSLambda> 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<RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES> 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<RAY_FLAG_SKIP_PROCEDURAL_PRIMITIVES> 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

​

Intégration à PIX

​

Voir aussi