Development

Frame graphs and typed render profiles

A profile binds a graph to a canonical runtime handle. Low-level callers create a profile with RendererRuntime::CreateProfile and register typed passes through its FrameGraphSystem. Compile the terminal you actually submit. Its declared reads and writers drive dependencies, resource lifetimes, access transitions, and which branches run.

Deduce a recipe from its passes

TRenderProfile adds compile-time contracts to the same graph and handle. Use ProfilePass to bind each slot tag to a factory, TProfileResource for typed resource contracts, and MakeRenderProfileRecipe to deduce the profile contract. A factory returns a concrete TProfilePassInstance with native pass, input, and output values. Optional and fallible factory results are supported. Required consumers still need a valid producer or an external resource declaration.

This example creates a real raster pass that clears its external color target. The application supplies the view and Core preparation context. The red value is construction-time state, so editing it prepares another profile.

#include <string_view>
#include <tuple>
#include <utility>

#include <Renderer/Runtime/TRenderProfile.h>

namespace SnAPI::Renderer::Docs
{
    struct ClearSlot
    {
        static constexpr std::string_view Name{"Clear"};
    };

    struct ColorSlot
    {
        static constexpr std::string_view Name{"Color"};
    };

    using ColorOutput = TProfileResource<ColorSlot, FrameGraphRenderTargetRef>;

    struct ClearInputs {};
    struct ClearOutput { ResourceName Target; };

    class ClearPass final : public TRasterPass<ClearInputs, ClearOutput>
    {
    public:
        explicit ClearPass(float red) : m_Red(red) {}

        void DeclareResources(ResourceBuilder&, const ClearInputs&) override {}

        void DeclareResources(ResourceBuilder& builder, const ClearInputs&, const ClearOutput& output)
        {
            builder.WriteExternalRenderTarget(output.Target, EPassResourceAccess::ColorWrite);
        }

        void Setup(const PassSetupContext&, const ClearInputs&) override {}

        void Record(const RasterPassRecordContext& context, const ClearInputs&, const ClearOutput& output) override
        {
            context.RecordClearColor(output.Target, {m_Red, 0.0f, 0.0f, 1.0f});
        }

    private:
        float m_Red;
    };

    struct Options
    {
        float Red{0.18f};

        static constexpr auto InspectableSettings()
        {
            // This example stores the value in the pass at construction, so it is structural.
            return std::tuple{TProfileSettingField<&Options::Red>{"red", "Red"}};
        }
    };

    auto ClearRecipe()
    {
        return MakeRenderProfileRecipe(
            Options{}, RenderProfileDesc{}, ColorOutput::Ref().ResourceName,
            ProfilePass<ClearSlot, std::tuple<>, std::tuple<ColorOutput>>(
                [](const Options& options, const ProfileBuildContext&)
                {
                    return TProfilePassInstance{
                        ClearPass{options.Red}, ClearInputs{},
                        ClearOutput{ColorOutput::Ref().ResourceName}};
                }));
    }

    using ClearProfile = TRenderProfile<TProfileSettings<Options>,
        TProfilePass<ClearSlot, ClearPass, std::tuple<>, std::tuple<ColorOutput>>>;

    Core::TTask<TResult<ClearProfile>> PrepareClearProfile(
        RendererRuntime& runtime, RenderScene& scene, RenderView view,
        PassResourcePreparationContext context)
    {
        co_return co_await CreateRenderProfileAsync(
            runtime, scene, view, ClearRecipe(), std::move(context));
    }

    Core::TTask<TResult<void>> SetClearRed(
        ClearProfile& profile, float red, PassResourcePreparationContext context)
    {
        co_return co_await profile.EditAsync<&Options::Red>(red, std::move(context));
    }
}

Use Handle() and Output() to submit through the ordinary runtime. Pass<Slot>() selects one tagged pass instance and yields a typed result. A recipe may contain multiple instances of the same concrete pass class, each with its own tag. Reacquire borrowed pass or settings references after a structural edit.

Edit settings with the right mutability

Pass settings can publish TSettingField metadata from InspectableSettings(). Profile settings can publish TProfileSettingField metadata. These describe stable keys, member types, and the edit policy. The choices are runtime dynamic, profile rebuild, and shader recompilation. A type match alone cannot make a shader or graph change dynamic.

A typed profile supports both EditAsync<&Options::Member> and the pass-slot form EditAsync<Slot, &Settings::Member>. A live profile edit uses the recipe’s live application hook. A structural edit copies a snapshot of the recipe and prepares a distinct candidate. During that preparation continue submitting the current handle. After safe publication, the old profile retires through GPU completion.

A tool using raw handles or a supplied bundle can use ProfileSettingsEditor with a caller-owned TProfileSettingsTarget. It supports reflected pass keys and typed fields. A structural operation needs a factory that returns the new ready bundle. Drive the returned task to completion and inspect both the result and active selection if retirement reports an error after publication. A newer admitted edit can supersede in-flight preparation.