How-To: Brightness & Safe Zone Calibration

Goal: give the player a full-screen gamma calibration screen and a title-safe frame screen, both adjusted live so they judge the real picture instead of a preview.

1. What already exists

Both screen classes are Abstract UCommonActivatableWidgets that also implement ICrimsonSettingActionInterface - the plugin ships behavior, you author the Widget Blueprint. Each action row supplies a child scalar setting rather than being a plain button, which is what makes Done write through the registry so the change tracker sees it and Apply lights up. Writing UCrimsonSettingsLocal directly would land the value and leave the screen looking untouched.

2. Author the screen widgets

Create a Widget Blueprint parented to each class and give it these binds. Both classes want the same four names.

Then add the instrument each screen needs between its heading and the instruction line: for brightness, a step wedge with a low-value mark overlaid on the black end (the player raises gamma until the mark stops separating from its background); for safe zone, a frame outline wrapped in a SafeZone whose slot has bIsTitleSafe set and SafeAreaScale 1 on all four sides.

3. Push them when a row fires

An action row broadcasts the registry's named-action event with the setting and its action tag. Subscribe on your screen, match the tag, push the matching widget onto your Menu layer, and call ExecuteActionForSetting(ActionTag, Setting) on it so it knows which child setting to write through.

// MySettingsScreen.h
#include "Widgets/CrimsonSettingScreen.h"
#include "MySettingsScreen.generated.h"

UCLASS(Abstract)
class UMySettingsScreen : public UCrimsonSettingScreen
{
    GENERATED_BODY()

protected:
    virtual void NativeOnInitialized() override;

    UPROPERTY(EditDefaultsOnly, Category = "Editors")
    TSoftClassPtr<UCommonActivatableWidget> BrightnessEditorClass;

    UPROPERTY(EditDefaultsOnly, Category = "Editors")
    TSoftClassPtr<UCommonActivatableWidget> SafeZoneEditorClass;

private:
    void HandleNamedAction(UCrimsonSetting* Setting, FGameplayTag ActionTag);
};

// MySettingsScreen.cpp
#include "MySettingsScreen.h"
#include "CrimsonSettingRegistry.h"
#include "CrimsonSettingsTags.h"

void UMySettingsScreen::NativeOnInitialized()
{
    Super::NativeOnInitialized();

    if (UCrimsonSettingRegistry* Reg = GetOrCreateRegistry())
    {
        Reg->OnSettingNamedActionEvent.AddUObject(this, &ThisClass::HandleNamedAction);
    }
}

void UMySettingsScreen::HandleNamedAction(UCrimsonSetting* Setting, FGameplayTag ActionTag)
{
    if (ActionTag == CrimsonSettingsTags::Action_Brightness)
    {
        // Push BrightnessEditorClass onto your Menu layer, then call
        // ICrimsonSettingActionInterface::Execute_ExecuteActionForSetting(Widget, ActionTag, Setting).
    }
    else if (ActionTag == CrimsonSettingsTags::Action_SafeZone)
    {
        // Same, with SafeZoneEditorClass.
    }
    else if (ActionTag == CrimsonSettingsTags::Action_Benchmark)
    {
        RunHardwareBenchmark();
    }
}

4. Safe zone on desktop

To bring the row up on PC for calibration work, open the console in a PIE or standalone session and run:

r.DebugSafeZone.TitleRatio 0.9

That is the whole recipe. The CVar makes FDisplayMetrics::ApplyDefaultSafeZones fill TitleSafePaddingSize with 5% of the display on each edge and broadcasts FCoreDelegates::OnSafeFrameChangedEvent, which every live SSafeZone listens to - so the HUD insets immediately. Reopen the settings screen, or navigate away and back so the registry regenerates, and the Safe Zone row is there. r.DebugSafeZone.TitleRatio 1 puts it all back and the row disappears again.

The per-edge alternative, if you want asymmetric padding, is SafeZone.EnableOverrides 1 plus the four SafeZone.Ratio.* values. Unlike r.DebugSafeZone.TitleRatio these do not broadcast OnSafeFrameChangedEvent on change - the metrics rebuild inside UCrimsonSettingsLocal::IsTitleSafePaddingAvailable() is what picks them up, so open the settings screen after setting them.

See also

• How-To: Use the Ready-Made Collections - where both rows come from.
• How-To: First-Run Setup Wizard - the usual first place a player is asked to calibrate gamma.
• API Reference -> Presentation - UCrimsonBrightnessEditor and UCrimsonSafeZoneEditor.