refactor!: make Resource.GetOriginal() nullable and add RequireOriginal()

src/Beutl.Editor.Components/PathEditorTab/ViewModels/PathEditorViewModel.cs

@@ -120,7 +120,7 @@ private Matrix CalculateMatrix(Drawable.Resource drawable)
                 matrix *= Graphics.Matrix.CreateTranslation(thickness, thickness);
             }
 
-            Matrix mat = drawable.GetOriginal().GetTransformMatrix(frameSize, size, drawable);
+            Matrix mat = drawable.RequireOriginal().GetTransformMatrix(frameSize, size, drawable);
             matrix *= mat;
         }
 
@@ -180,7 +180,7 @@ public void StartEdit(Shape shape, IGeometryEditorContext context, Avalonia.Poin
                 point.ToBtlPoint(), geometryShapeResource.Pen, geometryShapeResource.Data);
             if (figure != null)
             {
-                var figContext = context.FindPathFigureContext(figure.GetOriginal());
+                var figContext = context.FindPathFigureContext(figure.RequireOriginal());
                 if (figContext != null)
                 {
                     StartEdit(figContext);

src/Beutl.Editor.Components/PathEditorTab/Views/PathEditorTabView.axaml.cs

@@ -157,7 +157,7 @@ private void UpdateBackgroundGeometry()
             {
                 using (var context = new GeometryContext { FillType = geometry.FillType })
                 {
-                    geometry.GetOriginal().ApplyTo(context, geometry);
+                    geometry.RequireOriginal().ApplyTo(context, geometry);
                     string s = context.NativeObject.ToSvgPathData();
 
                     var newGeometry = Avalonia.Media.PathGeometry.Parse(s);

src/Beutl.Engine.SourceGenerators/Emit/ResourceClassEmitter.cs

@@ -149,9 +149,14 @@ private static void EmitProperties(StringBuilder sb, string innerIndent, ClassIn
 
     private static void EmitGetOriginal(StringBuilder sb, string innerIndent, string currentTypeDisplay)
     {
-        sb.Append(innerIndent).AppendLine($"public new {currentTypeDisplay} GetOriginal()");
+        sb.Append(innerIndent).AppendLine($"public new {currentTypeDisplay}? GetOriginal()");
         sb.Append(innerIndent).AppendLine("{");
-        sb.Append(innerIndent).AppendLine($"    return ({currentTypeDisplay})base.GetOriginal();");
+        sb.Append(innerIndent).AppendLine($"    return ({currentTypeDisplay}?)base.GetOriginal();");
+        sb.Append(innerIndent).AppendLine("}");
+        sb.AppendLine();
+        sb.Append(innerIndent).AppendLine($"public new {currentTypeDisplay} RequireOriginal()");
+        sb.Append(innerIndent).AppendLine("{");
+        sb.Append(innerIndent).AppendLine($"    return ({currentTypeDisplay})base.RequireOriginal();");
         sb.Append(innerIndent).AppendLine("}");
     }
 
@@ -163,7 +168,7 @@ private static void EmitBindNodePortValues(StringBuilder sb, string innerIndent,
             sb.Append(innerIndent).AppendLine("public override void BindNodePortValues()");
             sb.Append(innerIndent).AppendLine("{");
             sb.Append(innerIndent).AppendLine("    base.BindNodePortValues();");
-            sb.Append(innerIndent).AppendLine("    var node = GetOriginal();");
+            sb.Append(innerIndent).AppendLine("    var node = RequireOriginal();");
 
             for (int i = 0; i < info.NodePortProperties.Length; i++)
             {

src/Beutl.Engine/Audio/Composing/Composer.cs

@@ -207,7 +207,7 @@ public void InvalidateCache()
     /// </summary>
     protected void ComposeSound(Sound.Resource resource, TimeRange timeRange)
     {
-        var sound = resource.GetOriginal();
+        var sound = resource.RequireOriginal();
         // Get or create cache entry
         if (!_audioCache.TryGetValue(sound, out var entry))
         {

src/Beutl.Engine/Audio/SoundGroup.cs

@@ -33,7 +33,7 @@ public override void Compose(AudioContext context, Sound.Resource resource)
         // そのまま通す
         foreach (var child in r.Children)
         {
-            var original = child.GetOriginal();
+            var original = child.RequireOriginal();
             if (original.TimeRange.Start < TimeRange.Start)
             {
                 var internalContext = new AudioContext(context.SampleRate, context.ChannelCount);
@@ -80,7 +80,7 @@ public override void Compose(AudioContext context, Sound.Resource resource)
 
         foreach (var child in r.Children)
         {
-            var original = child.GetOriginal();
+            var original = child.RequireOriginal();
             var internalContext = new AudioContext(context.SampleRate, context.ChannelCount);
             original.Compose(internalContext, child);
             foreach (AudioNode node in internalContext.Nodes)

src/Beutl.Engine/Engine/EngineObject.cs

@@ -379,15 +379,48 @@ public class Resource : IDisposable
             Dispose(false);
         }
 
-        private EngineObject _original = null!;
+        private EngineObject? _original;
 
         public int Version { get; set; }
 
         public bool IsEnabled { get; set; }
 
         public bool IsDisposed { get; private set; }
 
-        public EngineObject GetOriginal() => _original;
+        /// <summary>
+        /// Gets whether this resource has a backing engine object.
+        /// </summary>
+        /// <remarks>
+        /// Only <see cref="Update"/> attaches one, so a resource built through its public constructor rather
+        /// than through <see cref="ToResource"/> is detached.
+        /// </remarks>
+        public bool IsAttached => _original is not null;
+
+        /// <summary>
+        /// Gets the backing engine object, or <see langword="null"/> when <see cref="IsAttached"/> is false.
+        /// </summary>
+        /// <remarks>
+        /// A detached resource is a shape in-tree production code already mints and consumes:
+        /// <see cref="Beutl.Media.ColorExtensions.ToBrushResource"/> reached from <c>TextElementsBuilder</c>,
+        /// the <c>SolidColorBrush.Resource</c> and <c>Pen.Resource</c> that <c>FormattedTextParser</c> builds
+        /// for a stroke tag, and the <c>GradientStop.Resource</c> the Avalonia editor adapters build. This
+        /// returns <see langword="null"/> for every one of them. Use <see cref="RequireOriginal"/> when a null
+        /// backing object cannot be handled.
+        /// </remarks>
+        public EngineObject? GetOriginal() => _original;
+
+        /// <summary>
+        /// Gets the backing engine object, throwing when this resource is detached.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">
+        /// This resource has no backing engine object.
+        /// </exception>
+        public EngineObject RequireOriginal()
+        {
+            return _original ?? throw new InvalidOperationException(
+                $"{GetType()} was constructed directly rather than through {nameof(EngineObject)}.{nameof(ToResource)}, "
+                + "so it has no backing engine object to dispatch to.");
+        }
 
         public virtual void Update(EngineObject obj, CompositionContext context, ref bool updateOnly)
         {

src/Beutl.Engine/Graphics/AudioVisualizers/AudioVisualizerDrawable.cs

@@ -154,7 +154,7 @@ private void EnsureSamplesComposed(TimeSpan targetStart, TimeSpan targetDuration
             if (!needsRecompose) return;
 
             var targetRange = new TimeRange(targetStart, targetDuration);
-            Sound sound = _source.GetOriginal();
+            Sound sound = _source.RequireOriginal();
 
             if (!ReferenceEquals(_frameObjectsSource, _source))
             {

src/Beutl.Engine/Graphics/BrushConstructor.cs

@@ -249,7 +249,7 @@ private void ConfigureGradientBrush(SKPaint paint, GradientBrush.Resource gradie
             var drawable = drawableBrush.Drawable;
             using var node = new DrawableRenderNode(drawable);
             using var context = new GraphicsContext2D(node, new Size((int)Bounds.Width, (int)Bounds.Height), s);
-            drawable.GetOriginal().Render(context, drawable);
+            drawable.RequireOriginal().Render(context, drawable);
             var processor = new RenderNodeProcessor(node, true, s, MaxWorkingScale);
             var ops = processor.RasterizeToRenderTargets();
             var totalBounds = ops.Aggregate(Rect.Empty, (current, item) => current.Union(item.Bounds));

src/Beutl.Engine/Graphics/DrawablePresenter.cs

@@ -19,7 +19,7 @@ public DrawablePresenter()
     public override void Render(GraphicsContext2D context, Drawable.Resource resource)
     {
         var r = (Resource)resource;
-        r.Target?.GetOriginal().Render(context, r.Target);
+        r.Target?.RequireOriginal().Render(context, r.Target);
     }
 
     protected override void OnDraw(GraphicsContext2D context, Drawable.Resource resource)
@@ -29,6 +29,6 @@ protected override void OnDraw(GraphicsContext2D context, Drawable.Resource reso
     protected override Size MeasureCore(Size availableSize, Drawable.Resource resource)
     {
         var r = (Resource)resource;
-        return r.Target?.GetOriginal().MeasureInternal(availableSize, r.Target) ?? Size.Empty;
+        return r.Target?.RequireOriginal().MeasureInternal(availableSize, r.Target) ?? Size.Empty;
     }
 }

src/Beutl.Engine/Graphics/DrawableTimeController.cs

@@ -154,13 +154,13 @@ private TimeSpan CalculateTargetTime(TimeSpan currentTime, Resource resource, Dr
     public override void Render(GraphicsContext2D context, Drawable.Resource resource)
     {
         var r = (Resource)resource;
-        r.Target?.GetOriginal().Render(context, r.Target);
+        r.Target?.RequireOriginal().Render(context, r.Target);
     }
 
     protected override Size MeasureCore(Size availableSize, Drawable.Resource resource)
     {
         var r = (Resource)resource;
-        return r.Target?.GetOriginal().MeasureInternal(availableSize, r.Target) ?? Size.Empty;
+        return r.Target?.RequireOriginal().MeasureInternal(availableSize, r.Target) ?? Size.Empty;
     }
 
     protected override void OnDraw(GraphicsContext2D context, Drawable.Resource resource)

src/Beutl.Engine/Graphics/FilterEffects/DelayAnimationEffect.cs

@@ -27,7 +27,7 @@ public override void ApplyTo(FilterEffectContext context, FilterEffect.Resource
         var r = (Resource)resource;
         if (r.Effect == null) return;
 
-        var childEffect = r.Effect.GetOriginal();
+        var childEffect = r.Effect.RequireOriginal();
 
         context.CustomEffect(
             (delay: r.Delay, globalTime: r.GlobalTime, childEffect, cache: r.DelayedResources,

src/Beutl.Engine/Graphics/FilterEffects/DisplacementMapEffect.cs

@@ -86,7 +86,7 @@ public override void ApplyTo(FilterEffectContext context, FilterEffect.Resource
         }
         else if (r.Transform is { } transform)
         {
-            transform.GetOriginal().ApplyTo(displacementMap, transform, r.SpreadMethod, r.Channel, r.Signed, context);
+            transform.RequireOriginal().ApplyTo(displacementMap, transform, r.SpreadMethod, r.Channel, r.Signed, context);
         }
     }
 }

src/Beutl.Engine/Graphics/FilterEffects/FilterEffectGroup.cs

@@ -19,7 +19,7 @@ public override void ApplyTo(FilterEffectContext context, FilterEffect.Resource
         var r = (Resource)resource;
         foreach (FilterEffect.Resource item in r.Children)
         {
-            item.GetOriginal().ApplyTo(context, item);
+            item.RequireOriginal().ApplyTo(context, item);
         }
     }
 }

src/Beutl.Engine/Graphics/FilterEffects/FilterEffectPresenter.cs

@@ -20,6 +20,6 @@ public override void ApplyTo(FilterEffectContext context, FilterEffect.Resource
     {
         var r = (Resource)resource;
 
-        r.Target?.GetOriginal().ApplyTo(context, r.Target);
+        r.Target?.RequireOriginal().ApplyTo(context, r.Target);
     }
 }

src/Beutl.Engine/Graphics/ImmediateCanvas.cs

@@ -254,7 +254,7 @@ public void DrawDrawable(Drawable.Resource drawable)
     {
         using var node = new DrawableRenderNode(drawable);
         using var context = new GraphicsContext2D(node, LogicalSize, _currentDensity);
-        drawable.GetOriginal().Render(context, drawable);
+        drawable.RequireOriginal().Render(context, drawable);
         var processor = new RenderNodeProcessor(node, true, _currentDensity, MaxWorkingScale);
         processor.Render(this);
     }

src/Beutl.Engine/Graphics/Particles/ParticleRenderNode.cs

@@ -186,7 +186,7 @@ private static (RenderTarget, Drawable.Resource, int, float)? RenderDrawableToTa
         // 1920x1080 is only the logical measurement canvas; actual buffer is sized from drawable bounds.
         using (var gctx = new GraphicsContext2D(node, new Size(1920, 1080), nominalScale))
         {
-            drawable.GetOriginal().Render(gctx, drawable);
+            drawable.RequireOriginal().Render(gctx, drawable);
         }
 
         var processor = new RenderNodeProcessor(node, false, nominalScale, maxWorkingScale);

src/Beutl.Engine/Graphics/Rendering/FilterEffectRenderNode.cs

@@ -44,7 +44,7 @@ public override RenderNodeOperation[] Process(RenderNodeContext context)
         workingScale = RenderNodeContext.ClampWorkingScaleToBufferBudget(bounds, workingScale);
 
         using var feContext = new FilterEffectContext(bounds, context.OutputScale, workingScale);
-        FilterEffect.Value.Resource.GetOriginal().ApplyTo(feContext, FilterEffect.Value.Resource);
+        FilterEffect.Value.Resource.RequireOriginal().ApplyTo(feContext, FilterEffect.Value.Resource);
         var effectTargets = new EffectTargets();
         effectTargets.AddRange(context.Input.Select(i => new EffectTarget(i)));
 

src/Beutl.Engine/Graphics/Rendering/GraphicsContext2D.cs

@@ -295,7 +295,7 @@ public void DrawDrawable(Drawable.Resource drawable)
         int count = _nodes.Count;
         try
         {
-            var obj = drawable.GetOriginal();
+            var obj = drawable.RequireOriginal();
             obj.Render(this, drawable);
         }
         finally

src/Beutl.Engine/Graphics/Rendering/Renderer.cs

@@ -203,7 +203,7 @@ private void RenderObjects(CompositionFrame frame)
 
     private Entry RenderDrawable(Drawable.Resource resource)
     {
-        var drawable = resource.GetOriginal();
+        var drawable = resource.RequireOriginal();
         Entry entry;
         bool shouldRender;
 
@@ -341,7 +341,7 @@ public void UpdateFrame(CompositionFrame frame)
             if (obj is not Drawable.Resource drawableResource)
                 continue;
 
-            var drawable = drawableResource.GetOriginal();
+            var drawable = drawableResource.RequireOriginal();
             Entry entry;
             bool shouldRender;
 
@@ -400,7 +400,7 @@ public void UpdateFrame(CompositionFrame frame)
 
     public Rect[] GetBoundaries(int zIndex)
     {
-        return [.. _allCurrentEntries.Where(e => e.Node.Drawable?.Resource.GetOriginal().ZIndex == zIndex).Select(e => e.Bounds)];
+        return [.. _allCurrentEntries.Where(e => e.Node.Drawable?.Resource.RequireOriginal().ZIndex == zIndex).Select(e => e.Bounds)];
     }
 
     public Rect? GetBoundary(Drawable drawable)
@@ -434,7 +434,7 @@ public Rect[] GetBoundaries(int zIndex)
 
     public Rect[] RecalculateBoundaries(int zIndex)
     {
-        return [.. _allCurrentEntries.Where(e => e.Node.Drawable?.Resource.GetOriginal().ZIndex == zIndex).Select(e =>
+        return [.. _allCurrentEntries.Where(e => e.Node.Drawable?.Resource.RequireOriginal().ZIndex == zIndex).Select(e =>
         {
             var processor = new RenderNodeProcessor(e.Node, CacheOptions.IsEnabled, OutputScale, MaxWorkingScale);
             var ops = processor.PullToRoot();

src/Beutl.Engine/Graphics3D/Meshes/Mesh.cs

@@ -111,7 +111,7 @@ private void EnsureCached()
             {
                 _capturedVersion = Version;
                 BuffersDirty = true;
-                GetOriginal().ApplyTo(this, out _cachedVertices!, out _cachedIndices!);
+                RequireOriginal().ApplyTo(this, out _cachedVertices!, out _cachedIndices!);
             }
         }
 

src/Beutl.Engine/Graphics3D/Textures/DrawableTextureSource.cs

@@ -74,7 +74,7 @@ public partial class Resource
                 using (var context = new GraphicsContext2D(
                            _drawableNode, new Size(textureWidth, textureHeight), density))
                 {
-                    Drawable.GetOriginal().Render(context, Drawable);
+                    Drawable.RequireOriginal().Render(context, Drawable);
                 }
 
                 var processor = new RenderNodeProcessor(_drawableNode, true, density, density);

src/Beutl.Engine/Media/Geometry/Geometry.cs

@@ -46,7 +46,7 @@ internal SKPath GetCachedPath()
                 _cachedStrokePath?.Dispose();
                 _cachedStrokePath = null;
                 _cachedPath?.Dispose();
-                var geometry = GetOriginal();
+                var geometry = RequireOriginal();
 
                 _cachedPath = new GeometryContext { FillType = FillType };
                 geometry.ApplyTo(_cachedPath, this);

src/Beutl.Engine/Media/Geometry/PathFigure.cs

@@ -59,7 +59,7 @@ public void ApplyTo(IGeometryContext context, Resource resource)
                 continue;
             }
 
-            item.GetOriginal().ApplyTo(context, item);
+            item.RequireOriginal().ApplyTo(context, item);
         }
 
         if (resource.IsClosed)

src/Beutl.Engine/Media/Geometry/PathGeometry.cs

@@ -157,7 +157,7 @@ public override void ApplyTo(IGeometryContext context, Geometry.Resource resourc
 
         foreach (PathFigure.Resource item in r.Figures)
         {
-            item.GetOriginal().ApplyTo(context, item);
+            item.RequireOriginal().ApplyTo(context, item);
         }
     }
 
@@ -171,7 +171,7 @@ public override void ApplyTo(IGeometryContext context, Geometry.Resource resourc
             using (var context = new GeometryContext())
             {
                 context.FillType = r.FillType;
-                item.GetOriginal().ApplyTo(context, item);
+                item.RequireOriginal().ApplyTo(context, item);
                 if (r.Transform != null)
                 {
                     context.Transform(r.Transform.Matrix);

src/Beutl.Engine/Media/TextFormatting/FormattedText.cs

@@ -67,7 +67,7 @@ public void Dispose()
     // which the resource's cached render path does not cover.
     private static void DisposePathListEntry(SKPathGeometry.Resource? resource)
     {
-        resource?.GetOriginal().Dispose();
+        resource?.RequireOriginal().Dispose();
         resource?.Dispose();
     }
 
@@ -341,7 +341,7 @@ private void Measure()
                     else
                     {
                         // SetSKPath reuses the slot without bumping Version, so invalidate the caches explicitly.
-                        exist.GetOriginal().SetSKPath(tmp, false);
+                        exist.RequireOriginal().SetSKPath(tmp, false);
                         exist.InvalidateCachedPaths();
                     }
                 }
@@ -362,7 +362,7 @@ private void Measure()
                 else
                 {
                     // Empty glyph: invalidate the caches so the reused slot stops serving the old path.
-                    exist.GetOriginal().SetSKPath(tmp, false);
+                    exist.RequireOriginal().SetSKPath(tmp, false);
                     exist.InvalidateCachedPaths();
                 }
             }

src/Beutl.NodeGraph/Composition/GraphSnapshot.cs

@@ -249,7 +249,7 @@ private void BuildInputConnectionMap(List<ConnectionSnapshot> connectionList)
         // 各 ListInputPort について、Connections の順序で登録
         for (int resourceIdx = 0; resourceIdx < _resources.Length; resourceIdx++)
         {
-            var node = _resources[resourceIdx].GetOriginal();
+            var node = _resources[resourceIdx].RequireOriginal();
             for (int itemIdx = 0; itemIdx < node.Items.Count; itemIdx++)
             {
                 var item = node.Items[itemIdx];
@@ -362,7 +362,7 @@ internal void CollectListInputValues<T>(int slotIndex, int itemIndex, IList<T?>
 
     private void LoadAnimatedValues(GraphNode.Resource resource, TimeSpan time)
     {
-        var node = resource.GetOriginal();
+        var node = resource.RequireOriginal();
         for (int i = 0; i < node.Items.Count; i++)
         {
             INodeMember item = node.Items[i];
@@ -390,7 +390,7 @@ private void LoadAnimatedValues(GraphNode.Resource resource, TimeSpan time)
 
     private void PropagateOutputs(GraphNode.Resource resource)
     {
-        var node = resource.GetOriginal();
+        var node = resource.RequireOriginal();
         for (int itemIdx = 0; itemIdx < node.Items.Count; itemIdx++)
         {
             if (!_outputConnectionMap.TryGetValue((resource.SlotIndex, itemIdx), out var connIndices))