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.