Implementing Effects
A FilterEffect is an EngineObject that post-processes a render target. The shape of the code is the same as in Implementing a Drawing Object: declare a partial class, expose IExpressionProperty<T> members, and override ApplyTo on the auto-generated Resource, whose properties hold the evaluated values.
If you have not read the EngineObject reference yet, start there. The property system and Resource lifecycle are explained on that page.
1. The minimal effect
using Beutl.Graphics.Effects;
namespace MyExtension;
public sealed partial class MyFilterEffect : FilterEffect
{
public MyFilterEffect()
{
ScanProperties<MyFilterEffect>();
}
public new partial class Resource
{
protected override void ApplyTo(FilterEffectContext context)
{
// Add filter operations to context here.
}
}
}
Two differences compared to Drawable:
ApplyToreceives only aFilterEffectContext. InsideResource, a property name is the value evaluated at the rendered time, so there is nothing to cast.RequireOriginal()returns the effect when a method needs state that is not a property.- There is no
MeasureCoreorOnDraw. The editor pipes the render target throughFilterEffectContextfor you, so you only describe how to transform it.
2. Combining existing effects
The simplest custom effects layer Beutl's built-in operations through the methods on FilterEffectContext. Bounds expansion (e.g. blur enlarging the surface) is handled internally, so you rarely need to adjust sizes yourself.
using System.ComponentModel.DataAnnotations;
using Beutl;
using Beutl.Engine;
using Beutl.Graphics;
using Beutl.Graphics.Effects;
using Beutl.Graphics.Rendering;
using Beutl.Media;
namespace MyExtension;
public sealed partial class HighContrastBlur : FilterEffect
{
public HighContrastBlur()
{
ScanProperties<HighContrastBlur>();
}
[Display(Name = "Blur Sigma")]
[Range(0, float.MaxValue)]
public IExpressionProperty<float> BlurSigma { get; } = Property.CreateAnimatable<float>(20);
[Display(Name = "Contrast")]
[Range(-100, 100)]
public IExpressionProperty<float> Contrast { get; } = Property.CreateAnimatable<float>(20);
public new partial class Resource
{
protected override void ApplyTo(FilterEffectContext context)
{
context.Blur(new Size(BlurSigma, BlurSigma));
context.HighContrast(
grayscale: false,
invertStyle: HighContrastInvertStyle.NoInvert,
contrast: Contrast / 100f);
}
}
}
FilterEffectContext exposes a method for each built-in operation: Blur, DropShadow, InnerShadow, Erode, Dilate, ColorMatrix, Saturate, HueRotate, Brightness, HighContrast, Lighting, MatrixConvolution, Transform, BlendMode, and more. See FilterEffectContext.cs and FilterEffectContext.Operations.cs for the complete list.
Crop(Rect, GradientSpreadMethod = Decal) crops in the coordinates of Bounds. The default Decal makes pixels outside the rectangle transparent and shrinks the bounds. Pad extends edge pixels, Repeat tiles, and Reflect mirrors the crop while retaining the original bounds.
For GLSL with multiple inputs or multiple passes, also see C# Script.
Resource.ApplyTo is protected. To apply another effect, such as a composite's child, call context.Apply(childResource), which keeps continuation boundaries and the enabled state.
Migrating from preview.9
In preview.9 ApplyTo lived on the effect class and received a resource argument. There are no compatibility shims: move the body into the nested Resource, replace r.Property with Property, and rebuild.
| Before | After |
|---|---|
override void FilterEffect.ApplyTo(FilterEffectContext, Resource) | protected override void ApplyTo(FilterEffectContext) in the effect's Resource |
effect.ApplyTo(context, resource) | context.Apply(resource) |
3. Processing the render target directly
See FlatShadow.cs, ColorShift.cs, and GLSLScriptEffect.cs as references.
CustomEffect(data, action, transformBounds) receives explicit state and computes output bounds from that state. If output bounds cannot be known during recording, the overload without transformBounds leaves them symbolic until the owning target's finite domain is available. Keep metadata callbacks independent of mutable editing objects.
FilterEffectContext.Shader(ShaderDescription) and Geometry(GeometryDescription) record deferred operations with explicit bounds and hit-test contracts. Use RenderHitTestContract.None, OutputBounds, AnyInput, or Custom(...) to state how the operation participates in selection; default(RenderHitTestContract) is invalid. A custom callback can receive state through Custom(state, static (state, context, point) => ...).
An AppendSkiaFilter factory must only produce its filter. It must not re-enter its FilterEffectExecutor through Activate, Flush, or related methods. Put target drawing in a CustomEffect action instead.
A CustomEffect callback run by the renderer cannot launch another RenderNodeRenderer, including through DrawDrawable or DrawNode on a canvas from Open; such a call throws InvalidOperationException. Record the drawable into a RenderNode, render it with CustomFilterEffectContext.ExecutionContext.RenderDependency(root, identity, domain), and draw the returned image. The dependency shares the request's allocation, working density, cancellation and cycle detection. A repeated identity reuses the image only within the same recorded effect. ExecutionContext is null when the effect runs outside the renderer.
Since preview.14, each raster that a callback reads describes where it lies with a RenderPlacement: Placement on an EffectTarget, a RenderExecutionInput, a MaterializedInputDescription, an OpaqueRenderOutput and a RenderCallbackCanvas, and OutputPlacement on a GeometrySession, an OpaqueRenderSession and a ShaderExecutionContext. Its LogicalBounds, Scale, DeviceBounds, DeviceGridOffset, LogicalOrigin and RasterBounds, with ToLogical and ToDevice, relate local coordinates to pixels the same way everywhere, and Scale.Value is the working density. Move content with EffectTarget.Bounds: the raster moves with it on the same allocation.
ContinuationEffect(data, action) hands its callback a FilterEffectContinuation for the operations recorded after it, to run any number of times or not at all. TargetEffect(data, action) hands its callback a CompositionTargetAccess, whose Capture() and Replace(image) read and replace the composition target beneath the effect. Since preview.12, its LocalToDevice maps the effect's local coordinates to pixels of the captured image, including the translation and the render density. The resource recording them must return true from ControlsContinuation or MayAccessTarget respectively, for every evaluation time. The engine splits chains and routes target work from these declarations before recording, so an undeclared recording throws.
Metadata callback diagnostics
If the compiler reports BESG004, check the values read by the metadata callback and any helpers it calls. Pass those values through explicit state or bound render resources instead of reading mutable static state.
4. Declarative shader graphs
context.ShaderGraph(state, record) records multi-pass GLSL graphics and compute work without an execution callback. The record callback runs synchronously while recording and only declares images, buffers and passes. The renderer compiles the programs, allocates and reuses images, and synchronizes the passes.
using System.ComponentModel.DataAnnotations;
using System.Numerics;
using Beutl;
using Beutl.Engine;
using Beutl.Graphics.Effects;
using Beutl.Graphics.Shaders;
namespace MyExtension;
public sealed partial class InvertGraphEffect : FilterEffect
{
private static readonly ShaderProgram s_invert = ShaderProgram.Fullscreen(new ShaderSource("""
#version 450
layout(binding = 0) uniform sampler2D image;
layout(binding = 1, std140) uniform Source { vec4 logical; vec4 raster; vec4 size; } src;
layout(binding = 2, std140) uniform Destination { vec4 logical; vec4 raster; vec4 size; } dst;
layout(push_constant) uniform Values { vec4 value; } pc;
layout(location = 0) out vec4 color;
void main() {
vec2 position = dst.raster.xy + gl_FragCoord.xy / dst.size.z;
vec4 sampled = texture(image, (position - src.raster.xy) / src.raster.zw);
color = vec4(mix(sampled.rgb, sampled.a - sampled.rgb, pc.value.x), sampled.a);
}
"""));
public InvertGraphEffect()
{
ScanProperties<InvertGraphEffect>();
}
[Display(Name = "Amount")]
[Range(0, 100)]
public IExpressionProperty<float> Amount { get; } = Property.CreateAnimatable(100f);
public new partial class Resource
{
protected override void ApplyTo(FilterEffectContext context)
{
context.ShaderGraph(new Vector4(Amount / 100f, 0, 0, 0), static (graph, values) =>
{
ShaderImage output = graph.Image2D("output", graph.Source);
graph.Fullscreen("invert", s_invert, pass =>
{
pass.SampledImage(0, graph.Source);
pass.ImageParameters(1, graph.Source);
pass.ImageParameters(2, output);
pass.PushConstants(values);
pass.InputRegion(0, ShaderInputRegion.Identity);
pass.ColorAttachment(0, output);
});
return graph.Output(output);
});
}
}
}
graph.Sourceis the complete incoming image. A pass reads it only through its ownSampledImagebinding.graph.Image2D(name, like, format, padding, resolutionScale)declares an image with the bounds of another one.graph.Fullscreen,graph.Renderandgraph.Computerecord passes, andShaderProgram.Fullscreen,GraphicsandComputecreate their programs.pass.ImageParameters(binding, image)binds three std140vec4values: the logical bounds, the raster bounds in the same coordinates, and (pixel width, pixel height, raster scale, 0).pass.PushConstants(value)copies an unmanaged value of up to 128 bytes, in multiples of four.pass.DispatchImage(image), new in preview.11, runs one compute invocation per texel ofimage, rounded up to the compiled local size. The size is resolved when the graph executes, so it covers an image the size of the composition at any working scale; the shader must guard the extra invocations.pass.InputRegion(binding, region)declares the complete sampling footprint of a sampled image and enables partial rendering. Without it orPartialRendering(), the pass runs in full.graph.Output(image)selects the result, which is linear premultiplied unless you pass anotherColorEncoding.
WaveRefraction.cs and LightRays.cs in the Beutl source are complete multi-pass examples.
5. Evaluating the input at another time
An effect that needs other moments of its input, such as a motion blur, overrides UsesInputEvaluation, PrepareInput and RenderInput on its Resource. An ordinary ApplyTo effect needs none of these.
using System.ComponentModel.DataAnnotations;
using Beutl;
using Beutl.Composition;
using Beutl.Engine;
using Beutl.Graphics;
using Beutl.Graphics.Effects;
using Beutl.Graphics.Rendering;
namespace MyExtension;
public sealed partial class EchoEffect : FilterEffect
{
public EchoEffect()
{
ScanProperties<EchoEffect>();
}
[Display(Name = "Delay (seconds)")]
[Range(0, 10)]
public IExpressionProperty<float> DelaySeconds { get; } = Property.CreateAnimatable(0.25f);
public new partial class Resource
{
private FilterEffectInputSample? _current;
private FilterEffectInputSample? _delayed;
public override bool UsesInputEvaluation => true;
// RenderInput records the samples, so there is nothing to apply to the pixels.
protected override void ApplyTo(FilterEffectContext context)
{
}
public override bool PrepareInput(FilterEffectInputContext input)
{
MediaTime time = input.EvaluationContext.Time;
_current = input.Evaluate(time);
_delayed = input.Evaluate(time - MediaTime.FromSeconds(DelaySeconds));
return true;
}
public override void RenderInput(GraphicsContext2D context, FilterEffectInputContext input)
{
DrawSample(_delayed!);
DrawSample(_current!);
void DrawSample(FilterEffectInputSample sample)
{
using (context.PushBlendMode(BlendMode.Plus))
using (context.PushOpacity(0.5f))
sample.Draw(context);
}
}
partial void PostReconcile(EchoEffect obj, CompositionContext context) => ClearSamples();
partial void PostDispose(bool disposing) => ClearSamples();
private void ClearSamples()
{
_current = null;
_delayed = null;
}
}
}
PrepareInputruns after the source is reconciled, even when current-time values did not change. Callinput.Evaluate(time)for every sample there, so their dependencies, bounds and 3D requirements are known before recording, and returntrueto supply the replacement drawing.input.EvaluationContextcaptures the input's clock and itsConditions: the effective outputFrameRate, proxy policy, target domain, scene queries and cancellation token. LetOperationCanceledExceptionpropagate.sample.Draw(context)records the sample with its own transform, opacity and preceding effects, in the drawable's parent coordinates. The engine then runs the following effects on the replacement once and composites the owner's blend mode once. Do not reapply the drawable's transform or opacity, and do not clip to its current bounds.- The engine owns the samples until the source's next reconciliation or disposal, so clear your references in
PostReconcileandPostDispose. - In a custom execution callback,
ExecutionContext.RenderDependency(sample, availableSize, domain)renders a sample through the current request. Choose a finite, non-empty domain in parent coordinates, and dispose the returned image lease.
CompositionContext.EvaluationServices, which is also available through input.EvaluationContext, answers read-only queries about the scene being evaluated: GetLayers(time), EvaluateLayer(zIndex, time), ReadLayer, TryReadFrame and ReadAudio(start, duration). A detached evaluation may leave it null. TryReadFrame returns false until evaluation completes, so read it from a render-time callback. For an audio-reactive effect, AudioSpectrum.Calculate(samples, magnitudes) computes frequency magnitudes from a power-of-two number of samples.
6. Register the effect in your extension
using Beutl.Extensibility;
using Beutl.Services;
using Microsoft.Extensions.DependencyInjection;
namespace MyExtension;
[Export]
public sealed class MyEffectExtension : Extension
{
public override string Name => "My Effects";
public override string DisplayName => "My Effects";
public override void Load(IExtensionContext context)
{
context.Services.GetRequiredService<LibraryService>().Register<HighContrastBlur>(
KnownLibraryItemFormats.FilterEffect,
"High-Contrast Blur");
}
}
If you want to bundle several effects together, use the RegisterGroup helper described in the EngineObject reference to organize them under a single library category.
Library thumbnails
Since preview.12, the library tab and the effect picker show each effect as a moving thumbnail. Beutl applies the effect to the project's content, such as the frame the preview shows or the object the effect is being added to, or to a sample picture where there is none. An effect without a recipe plays at its default values over the landscape sample, and many effects change nothing at their defaults, so register a recipe for each of your effects when the extension loads:
using Beutl.Editor.Services.LibraryThumbnails;
namespace MyExtension;
public static class MyEffectThumbnails
{
// Call this from MyEffectExtension.Load(context).
public static void Register()
=> LibraryThumbnailRecipes.Register<HighContrastBlur>(
LibraryThumbnailSample.Landscape,
(effect, context) =>
{
effect.Contrast.Value = 40;
context.Animate(effect.BlurSigma, p => context.Scale(16) * LibraryThumbnailContext.Wave(p));
});
}
- The sample is the picture that shows the effect best where the project has no content:
Landscape,NightLights,GreenScreen,Object,TextorShapes. The overload without it usesLandscape. - Beutl calls the recipe with a new instance of the effect each time it draws the thumbnail. Set the values to show on that instance, and make a value move with
context.Animate(property, valueAt):valueAtreceives how far the thumbnail has played, from 0 at its start to 1 at its end, and runs on the render thread. - A thumbnail shows its middle frame at rest.
LibraryThumbnailContext.Wave(progress)rises from 0 to 1 at the middle and falls back, so a value animated with it is clearest at rest and loops without a jump. - The effect applies to the content at its size in the project. Give sizes for a picture 1080 units on its shorter side and pass them through
context.Scale(value), which fits them tocontext.Size, so a small object shows as much as a whole frame.context.Subjectis that picture, which a recipe can move for an effect that shows only on moving content. - A transition registers a recipe the same way; its
context.Subjectisnull. The recipes of an extension are removed when it unloads.
Reference files in the Beutl source
| File | What it teaches |
|---|---|
src/Beutl.Engine/Graphics/FilterEffects/HighContrast.cs | A minimal effect that delegates to a single FilterEffectContext call. |
src/Beutl.Engine/Graphics/FilterEffects/FlatShadow.cs | Custom drawing through CustomEffect, with transformBounds to expand the surface. |
src/Beutl.Engine/Graphics/FilterEffects/FilterEffectContext.cs | The full list of chainable built-in operations. |
src/Beutl.Engine/Graphics/FilterEffects/WaveRefraction.cs | A two-pass declarative shader graph. |
src/Beutl.Engine/Graphics/FilterEffects/MotionBlur.cs | Accumulating time samples of the input through PrepareInput and RenderInput. |
DiagnosticDescriptors.csFilterEffect.cs,FilterEffectContext.cs, andFilterEffectContext.Operations.csFilterEffectInputContext.csandFilterEffectContinuation.csEffectTarget.csandRenderPlacement.csRenderExecutionContext.cs,CompositionTargetAccess.cs, andRenderHitTestContract.csShaderGraphBuilder.csandShaderPassBuilder.csICompositionEvaluationServices.csandAudioSpectrum.csLibraryThumbnailRecipes.cs,LibraryThumbnailContext.cs, andLibraryThumbnailSample.csdrawing-on-resources-migration.mdandresolution-independent-rendering.md