Add SkSL image filter support (ToImageFilter / SKRuntimeImageFilterBuilder)

[mattleibow]

Add support for custom SkSL-based image filters via SKRuntimeEffect.ToImageFilter and SKRuntimeImageFilterBuilder. This wraps SkImageFilters::RuntimeShader (Skia m98+, maxSampleRadius m116+), enabling custom GPU image processing effects that compose with built-in filters.

Fixes #3776

API

SKRuntimeImageFilterBuilder (primary API)

using var builder = SKRuntimeEffect.BuildImageFilter(sksl);
builder.Uniforms["strength"] = 4.0f;

// Auto-detect single child, use source image
var filter = builder.Build();

// With maxSampleRadius for neighbor-sampling shaders
var filter = builder.Build(maxSampleRadius: 1.0f);

// Multi-child (e.g. unsharp mask)
builder.Inputs["content"] = null;   // source image
builder.Inputs["blurred"] = blur;   // blur filter
var filter = builder.Build();

SKRuntimeEffect.ToImageFilter (low-level)

effect.ToImageFilter()
effect.ToImageFilter(childShaderName, input)
effect.ToImageFilter(childShaderName, input, maxSampleRadius)
effect.ToImageFilter(uniforms, children)
effect.ToImageFilter(uniforms, children, childShaderName, input)
effect.ToImageFilter(uniforms, children, childShaderName, input, maxSampleRadius)
effect.ToImageFilter(uniforms, children, inputs)
effect.ToImageFilter(uniforms, children, inputs, maxSampleRadius)

New types

• SKRuntimeImageFilterBuilder — builder with Inputs property and Build() overloads
• SKRuntimeEffectImageFilterInputs — dictionary-backed collection mapping child shader names to SKImageFilter? inputs. Names/Count/Contains reflect set entries. Validates names against the effect.

C API (sk_runtimeeffect.h)

• sk_runtimeeffect_make_image_filter — single-child with maxSampleRadius
• sk_runtimeeffect_make_image_filter_with_children — multi-child, uses STArray for stack-backed allocations

Companion skia PR: mono/skia#202

Tests

18 tests in SKRuntimeEffectTest.ImageFilters:

• Auto-detect, named child, null name, with input filter, maxSampleRadius
• Multi-child creation and rendering
• Inputs: Names/Count/Contains, Reset, invalid name throws, null vs unset
• ToImageFilter directly on effect with/without explicit uniforms
• All objects properly disposed (GarbageCleanupFixture clean)

Gallery Samples

• Custom SkSL Image Filter — 5 interactive effects (invert, grayscale, sepia, vignette, edge detect). Cached builders.
• Unsharp Mask — Multi-child pattern. Cached builder, adjustable blur radius and strength.

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 3778

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 3778"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-3778/packages --name skiasharp-pr-3778

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-3778

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Site
🔗 View Staging Docs
🔗 View Staging Gallery (Blazor)
🔗 View Staging Gallery (Uno Platform)
🔗 View Staging SkiaFiddle

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

samples/Gallery/Shared/Samples/RuntimeShaderImageFilterSample.cs:113

• OnDestroy() does not call base.OnDestroy(). The base implementation handles cleanup for the animation refresh loop (CTS cancellation/disposal) and is called by other samples; please call base.OnDestroy() to keep lifecycle behavior consistent.

	protected override void OnDestroy()
	{
		sourceBitmap?.Dispose();
		sourceBitmap = null;
		for (var i = 0; i < cachedBuilders.Length; i++)
		{
			cachedBuilders[i]?.Dispose();
			cachedBuilders[i] = null;
		}
	}

samples/Gallery/Shared/Samples/UnsharpMaskSample.cs:54

• OnDestroy() does not call base.OnDestroy(). The base method cancels/disposes the animation refresh CTS; calling it keeps cleanup consistent with other samples and avoids leaks if animation is added later.

	protected override void OnDestroy()
	{
		sourceBitmap?.Dispose();
		sourceBitmap = null;
		builder?.Dispose();
		builder = null;
	}

[ramezgerges]

Review

C# side

🔴 Missing GC.KeepAlive across the new P/Invoke calls

The two new private methods omit the GC.KeepAlive calls that every sibling method in this file already performs. Compare:

// SKRuntimeEffect.cs — existing ToShader
fixed (IntPtr* ch = childrenHandles) {
    var shader = SkiaApi.sk_runtimeeffect_make_shader (...);
    GC.KeepAlive (uniforms);
    GC.KeepAlive (this);   // <-- present
    return shader;
}

// new ToImageFilterSingle — no KeepAlive
fixed (IntPtr* ch = childrenHandles) {
    return SKImageFilter.GetObject (SkiaApi.sk_runtimeeffect_make_image_filter (
        Handle, uniformsHandle, ch, (IntPtr)childrenHandles.Length,
        maxSampleRadius, childShaderName ?? string.Empty, input?.Handle ?? IntPtr.Zero));
}

Handle reads this, and after the last managed use the JIT may treat this (and the input filter in the single-child path) as collectible during the native call — the finalizer can then unref the underlying native object mid-call. This is exactly the lifetime failure class the recent hardening work targets ("Keep 'this' alive across instance P/Invoke calls", "Hold native-wrapper arguments alive across P/Invoke calls"), so the new entry points should match that pattern rather than regress it.

Requested change — in both ToImageFilterSingle and ToImageFilterMulti, inside the fixed block before returning, add:

• GC.KeepAlive(this)
• GC.KeepAlive(input) (single-child path)
• GC.KeepAlive(uniformData) — the using already covers it, but keep it explicit for parity with the sibling methods

C side (sk_runtimeeffect.cpp / sk_imagefilter.cpp)

🟡 Unused include in sk_imagefilter.cpp

The diff adds #include "include/effects/SkRuntimeEffect.h" to sk_imagefilter.cpp, but nothing in that file references it — the new runtime image-filter functions live entirely in sk_runtimeeffect.cpp. Please drop the include.

🟡 make_image_filter_with_children doesn't guard against null child-shader names

SkImageFilters::RuntimeShader's multi-child overload is documented to return nullptr if any name is null. But the shim constructs the string_view before the call:

names.push_back(std::string_view(childShaderNames[i]));   // strlen(nullptr) on a null entry = UB

std::string_view(const char*) on nullptr is UB (a crash), not a graceful null return. The single-child function guards this defensively (childShaderName ? std::string_view(childShaderName) : std::string_view()); the multi-child one does not. The C# layer never passes null names (they're validated Dictionary keys), so this is safe today and consistent with "the C API trusts the caller" — flagging it as an optional parity/robustness guard, not a blocker.

🟢 Factor the shared preamble into a helper (keep both entry points)

The two functions are near-identical in their preamble — same builder construction and child-binding loop:

SkRuntimeShaderBuilder builder(sk_ref_sp(AsRuntimeEffect(effect)), sk_ref_sp(AsData(uniforms)));
auto effectChildren = AsRuntimeEffect(effect)->children();
for (size_t i = 0; i < childCount && i < effectChildren.size(); i++) {
    builder.child(effectChildren[i].name) = sk_ref_sp(AsFlattenable(children[i]));
}

Extract that into a static helper and have both entry points call it:

static void sk_runtimeeffect_bind_children(
        SkRuntimeShaderBuilder& builder, sk_runtimeeffect_t* effect,
        sk_flattenable_t** children, size_t childCount) {
    auto effectChildren = AsRuntimeEffect(effect)->children();
    for (size_t i = 0; i < childCount && i < effectChildren.size(); i++) {
        builder.child(effectChildren[i].name) = sk_ref_sp(AsFlattenable(children[i]));
    }
}

Each function then becomes:

SkRuntimeShaderBuilder builder(sk_ref_sp(AsRuntimeEffect(effect)), sk_ref_sp(AsData(uniforms)));
sk_runtimeeffect_bind_children(builder, effect, children, childCount);
// ... single- or multi-child RuntimeShader call