メインコンテンツまでスキップ
バージョン: 2.0.0-preview

EngineObject リファレンス

EngineObject は Beutl 2.x で描画やコンポジションに使うオブジェクトの基底クラスです。Drawable・Shape・FilterEffect・Brush・Geometry など、タイムラインに配置できる型の大半はこのクラスを継承しています。先にこのページに目を通しておくと、他の拡張機能ガイドを大幅に短く読めるはずです。

EngineObject が提供するもの​

  • 値のプロパティ(IProperty<T>)、式を持つプロパティ(IExpressionProperty<T>)、リストのプロパティ(IListProperty<T>)。
  • 派生クラスに必要なボイラープレート(入れ子の Resource クラス、ToResource(...) メソッド、ScanPropertiesCore<T>())を自動生成するソースジェネレータ Beutl.Engine.SourceGenerators。
  • 時間範囲・Z インデックス・有効/無効といった共通機能の組み込み実装。

EngineObject の宣言​

要点は 2 つだけです。クラスを partial にすること、コンストラクタで ScanProperties<T>() を呼ぶこと。

using Beutl.Engine;

namespace MyExtension;

public sealed partial class MySampleObject : EngineObject
{
public MySampleObject()
{
ScanProperties<MySampleObject>();
}
}

partial 修飾子があるおかげで、ソースジェネレータが Resource クラスや ToResource メソッドを追加できます。ScanProperties<T>() は宣言された IProperty<T> メンバを走査し、エディタが表示・アニメーション化・シリアライズできる形で登録します。

実際の拡張機能では EngineObject を直接継承するよりも、Drawable / Shape / FilterEffect などのサブクラスを継承するのが普通です。代表的な継承先は共通の派生クラスを参照してください。

プロパティの宣言​

Property、IProperty<T>、IExpressionProperty<T>、IListProperty<T> は Beutl.Core の Beutl 名前空間にあります。Property.CreateAnimatable 拡張メンバを使うには Beutl.Engine もインポートします。

using System.ComponentModel.DataAnnotations;
using Beutl;
using Beutl.Engine;

namespace MyExtension;

public sealed partial class MyProperties : EngineObject
{
public MyProperties()
{
ScanProperties<MyProperties>();
}

[Display(Name = "Size")]
[Range(0, float.MaxValue)]
public IExpressionProperty<float> Size { get; } = Property.CreateAnimatable<float>(100);

[Display(Name = "Caption")]
public IExpressionProperty<string?> Caption { get; } = Property.CreateExpression<string?>();

public IProperty<bool> ShowLabel { get; } = Property.CreateValue(true);

public IListProperty<MyProperties> Children { get; } = Property.CreateList<MyProperties>();
}
ファクトリ戻り値用途
Property.CreateAnimatable<T>(defaultValue, validator)IExpressionProperty<T>キーフレームと式を使える値。引数はいずれも省略できます。
Property.CreateExpression<T>(defaultValue, validator)IExpressionProperty<T>式を使えて、キーフレームは使えない値。引数はいずれも省略できます。
Property.CreateValue<T>(defaultValue, validator)IProperty<T>式もキーフレームも使わない値。引数はいずれも省略できます。
Property.CreateReference<T>()IExpressionProperty<T>所有権を持たないオブジェクトへの参照。参照先を子として接続しません。
Property.CreateList<T>()IListProperty<T>所有する順序付きコレクション。プロパティ自体の Add、Remove、Clear を呼びます。

IProperty<T> は保存された Value、DefaultValue、ValueChanged、IsValueSet を公開します。Expression、HasExpression、IsAnimatable、Evaluate(EvaluationContext) など、式に関するメンバは IExpressionProperty<T> にあります。式を使えるかどうかは property is IExpressionProperty で調べます。SupportsExpression は削除されました。実装型の SimpleProperty<T>、ValueOnlyProperty<T>、ListProperty<T> も Beutl.Core にあります。

System.ComponentModel.DataAnnotations の検証属性(例: [Range])は自動で適用されます。[Display(Name = ..., ResourceType = ...)] はプロパティパネルに表示されるラベルを制御し、リソース型を介したローカライズにも対応します。

単位のメタデータには [Unit(PropertyUnit.Percent)]、[Unit(PropertyUnit.Degrees)]、[Unit(PropertyUnit.Ratio)] を使います。これらは Beutl 名前空間にあり、エディターの単位表示と Agent Toolkit のスキーマに使われます。

string のプロパティは、既定では 1 行で編集します。[DataType(DataType.MultilineText)] を付けると文章向けの複数行の欄になり、preview.13 以降は長い行を折り返します。シェーダーやスクリプトなどのソースコードには、preview.13 で追加された [DataType(CustomDataTypes.Code)] を使います。この欄も複数行ですが、等幅フォントで表示され、行を折り返さずに横にスクロールし、Tab キーはフォーカスを移動せずにインデントを入力します。Shift+Tab キーでは、これまでどおり前の欄に移動します。CustomDataTypes は Beutl 名前空間(Beutl.Core)にあり、IsCode() で DataTypeAttribute がコードを表すかどうかを判定できます。ノードでは、GraphNode の protected メソッド UseCodeEditor(NodeMember<string>) と UseMultilineEditor(InputPort<string>) がメンバーに対して同じことをします。

[Display(Name = "Script")]
[DataType(CustomDataTypes.Code)]
public IExpressionProperty<string> Script { get; } = Property.CreateExpression("");

値の読み書き​

プロパティオブジェクトの Value を読み書きします。継承した Name、Id、IsEnabled、ZIndex、TimeRange も同様です。これらのメンバには、別の静的な XxxProperty フィールドや値だけのアクセサーはありません。

using System;
using MyExtension;

var obj = new MyProperties
{
Name = { Value = "Example" },
Size = { Value = 120 },
IsEnabled = { Value = true }
};
obj.Children.Add(new MyProperties());
obj.Size.ValueChanged += (_, change) => Console.WriteLine(change.NewValue);

property.GetObservable() はスカラーのプロパティについて、購読時の値と、その後の値の変更を通知します。リストは CollectionChanged を監視します。リストの Value への代入は、所有者が保持するリストに内容をコピーします。プロパティ自体を監視してください。値が変わっても、一般に所有者から PropertyChanged("Size") は通知されません。ID の値を比較するときは a.Id.Value == b.Id.Value と書きます。プロパティオブジェクト同士の比較は参照の比較になり、診断 BESG007 が出ます。同じプロパティオブジェクトか調べたい場合だけ ReferenceEquals を使います。

以前のコードを移行するときは、CurrentValue を Value、GetValue(context) を Evaluate(context)、ReplaceCurrentValue(value) を SetValueEvenIfEqual(value)、HasLocalValue を IsValueSet に変更します。CoreProperty、ConfigureProperty、CoreObject.GetValue / SetValue は削除されました。エンジン以外の CoreObject 派生クラスも、同じプロパティ宣言と ScanProperties<T>() のパターンを使います。

キーフレームと式​

キーフレームは、プロパティの式の連鎖の最下層に置かれます。削除された IProperty.Animation と AnimationChanged の代わりに Beutl.Animation の拡張メソッドを使います。

using Beutl;
using Beutl.Animation;
using MyExtension;

var obj = new MyProperties();
var animation = new KeyFrameAnimation<float>();
animation.KeyFrames.Add(new KeyFrame<float>
{
KeyTime = { Value = MediaTime.Zero },
Value = { Value = 100 }
});
animation.KeyFrames.Add(new KeyFrame<float>
{
KeyTime = { Value = MediaTime.FromSeconds(1) },
Value = { Value = 200 }
});
obj.Size.SetKeyFrameAnimation(animation);
KeyFrameAnimation<float>? current = obj.Size.GetKeyFrameAnimation();

上位の式がない場合、Expression はキーフレームを返しますが、HasExpression はキーフレームを数えません。IAnimation、IAnimation<T>、非ジェネリックの KeyFrameAnimation は削除されました。IKeyFrameAnimation または KeyFrameAnimation<T> を使います。UseGlobalClock と、各キーフレームの KeyTime、Value、Easing もプロパティオブジェクトです。

プロパティのメニューの 成分を分離 を使うと、ベクトルや色などのプロパティは成分ごとに独立したトラックを持ちます。このときアニメーションは IComponentAnimation になり、GetKeyFrameAnimation は null を返します。両方の種類を扱うコードでは GetPropertyAnimation と SetPropertyAnimation を使ってください。KeyFrameAnimation<T> と成分のアニメーションはどちらも IPropertyAnimation を実装し、IPropertyAnimation<T>.EvaluateAt(time) でどちらの値も読み取れます。IComponentAnimation.Components は成分のプロパティの一覧です。ComponentAnimations.IsSupported(type)、Separate(property)、Unseparate(property, time) はメニューと同じ操作を行います。分離を解除すると、time で評価した値が保持されます。

IExpression、IExpression<T>、ExpressionContext、PropertyLookup、ExpressionException も Beutl.Core の Beutl 名前空間にあります。IExpressionProperty<T>.Evaluate は EvaluationContext、式の実装の IExpression<T>.Evaluate は ExpressionContext を受け取ります。式とコンポジションのコンテキストはともに EvaluationContext を継承します。ExpressionContext は CompositionContext を継承しません。

タイムラインとキーフレームの時刻には TimeSpan ではなく MediaTime を使います。フレームの時刻は MediaTime.FromFrames(frame, rationalRate) で作り、時間として表示するときは ToTimeSpan() で変換します。MediaTime.ToString() は flick 数を表示します。

2 つか 3 つのプロパティを 1 行で編集する​

アニメーション可能な 2 つの float または int プロパティのうち、1 つ目に [CombinedEditor(nameof(Second))] を付けると、両方がプロパティパネルではベクトルエディタの 1 行に、インライン表示では 1 つのレイヤーに、グラフエディタでは 1 行にまとまります。[CombinedEditor(nameof(Second), nameof(Third))] は、3 つの float プロパティを同じようにまとめます。各プロパティは、モデルでもファイルでも、それぞれの値、範囲、キーフレーム、式を保ちます。行の名前は [Display] と同じく Name と ResourceType で指定し、指定しない場合は 1 つ目のプロパティの名前になります。

using System.ComponentModel.DataAnnotations;
using Beutl;
using Beutl.Engine;

namespace MyExtension;

public sealed partial class MyPanel : EngineObject
{
public MyPanel()
{
ScanProperties<MyPanel>();
}

[Display(Name = "Width")]
[Range(0, float.MaxValue)]
[CombinedEditor(nameof(Height), Name = "Size")]
public IExpressionProperty<float> Width { get; } = Property.CreateAnimatable<float>(100);

[Display(Name = "Height")]
[Range(0, float.MaxValue)]
public IExpressionProperty<float> Height { get; } = Property.CreateAnimatable<float>(100);
}

1 つ目のプロパティの名前が Width で終わる場合、行は 2 つのプロパティを Size として編集し、それ以外の場合は Point として編集します(int では PixelSize と PixelPoint)。3 つの場合は Vector3 になります。プロパティは同じ EngineObject に Property.CreateAnimatable で宣言し、名前を一致させる必要があります。そうでない場合、各プロパティは別々の行のままです。ノードでは、各プロパティがそれぞれの行とポートを持ちます。

キーフレームの時刻、イージング、クロックが異なる間や、1 つの式を共有していない間は、行がプロパティごとに分かれ、一致すると再び 1 行にまとまります。メニューの 成分を分離 を使うと手動で分けられます。まとめた行では、これは表示だけを変え、パネルの表示状態として保存されます。まとめた行には、new Size(Sin(Time) * 100, 100) のように値全体を返す 1 つの式を設定できます。このような式のために、Size と Point に double, double のコンストラクターが追加されました。各プロパティは、この式を ComponentExpression<TValue, TComponent>(名前空間 Beutl.Engine.Expressions)として保存します。これは共有された式を評価してプロパティの成分を取り出し、プロパティのキーフレームをその下に保ちます。1 つのプロパティの Expression を読むコードは、これを受け取ることがあります。IComponentExpression からは Source、Component、ComponentIndex を取得できます。古いバージョンはこの新しい種類の式を失うため、preview.11 でファイル形式の下限を引き上げました。

自動生成される Resource クラス​

具象 partial class : EngineObject ごとに、ソースジェネレータが入れ子の Resource クラスを出力します。レンダリングパイプラインはこれを「ある時点でのオブジェクトのスナップショット」として扱うため、アニメーション・式・コンポジションシステムは編集中のインスタンスに触らずに値をサンプリングできます。

ジェネレータは ToResource(CompositionContext)、スナップショットのプロパティ、Reconcile(EngineObject, CompositionContext, ref bool versionBumped) を生成します。Reconcile はコンテキストの時刻で式を評価して子リソースを更新し、値が変わると Version を進めます。以前の Update、PreUpdate、PostUpdate は Reconcile、PreReconcile、PostReconcile に変わりました。

生成されたリソースは partial メソッドのフックで拡張できます。上の MyProperties に、次の partial 宣言を追加します。

using Beutl.Composition;

namespace MyExtension;

public sealed partial class MyProperties
{
public new partial class Resource
{
partial void PreReconcile(MyProperties obj, CompositionContext context)
{
}

partial void PostReconcile(MyProperties obj, CompositionContext context)
{
}

partial void PreDispose(bool disposing)
{
}

partial void PostDispose(bool disposing)
{
}
}
}

PostReconcile ではスナップショット値から派生データを作り、自分で所有するリソースは破棄時のフックで解放します。生成された実装は disposing が true のときに自身の子リソースを解放します。RectShape もこのパターンを使います。描画オブジェクトのガイド には、公開 API を使った拡張機能の完全な実装例があります。

別の EngineObject から派生したクラスでは、生成された Reconcile は、そのクラスの PreReconcile、基底クラスの Reconcile(基底クラスのフックを含みます)の順に実行し、そのあとでそのクラス自身のプロパティを評価して PostReconcile を実行します。そのため、AudioVisualizerDrawable.Resource が PostReconcile から ComputeSampleWindow を呼ぶように、基底クラスのフックからオーバーライドが呼ばれると、派生クラスのプロパティは前回の値のままで、新しいリソースでは既定値です。このようなオーバーライドが読む値は PreReconcile で評価し、_windowFftSize = context.Get(obj.FftSize) のように専用のフィールドに保持してください。_fftSize のように、ジェネレータがプロパティのために持つフィールドには書き込まないでください。生成された Reconcile は、新しい値をこのフィールドと比べて、リソースが変わったかどうかを判断します。

編集時 vs 描画時​

この 2 つのレイヤーを意識してください。

レイヤー型ライフタイム書き換える主体
編集時EngineObjectプロジェクト内に存続UI、スクリプト、デシリアライズ
描画時EngineObject.Resourceコンポジション用に生成・更新し、再利用する場合がある自動生成された Reconcile() とリソースのフック

レンダリング処理(Drawable.Resource.OnDraw、FilterEffect.Resource.ApplyTo など)は Resource の中に書くので、値はそのプロパティから読み取ります。Resource の中で Size のような名前が指すのは評価済みの値で、オブジェクトの IExpressionProperty<T> ではありません。IProperty<T>.Value を直接参照しないでください。Resource はアニメーションや式を考慮した「ある時点での値のスナップショット」なので、これを使うことで効率的に描画できます。EngineObject はあくまで編集用のオブジェクトです。プロパティ以外の状態が必要なメソッドでは、RequireOriginal() で取得できます。

フォールバック処理​

Drawable、Sound、EngineObject などの基底クラスには [FallbackType] が宣言されています。保存されたプロジェクトが利用できない拡張機能の型を参照している場合、対応するフォールバックがシリアライズされたデータを保持し、再保存できるようにします。フォールバックの描画オブジェクトは何も描画せず、失われた拡張機能の動作を代わりに実装するものではありません。

共通の派生クラス​

基底クラス名前空間役割実装ガイド
DrawableBeutl.Graphicsキャンバスに描画される任意のオブジェクト。Transform / Opacity / BlendMode / FilterEffect / アライメントを提供。描画オブジェクトを実装
ShapeBeutl.Graphics.Shapes見た目が Geometry で決まる Drawable。Fill と Pen を追加で持ちます。描画オブジェクトを実装
FilterEffectBeutl.Graphics.Effectsレンダーターゲットへ適用するポストエフェクト。エフェクトを実装する
SoundBeutl.Audioタイムラインに配置される任意の音源。Gain / Pan / SurroundPan / CenterLevel / LfeLevel / Speed / OffsetPosition / Effect を提供。
AudioEffectBeutl.Audio.EffectsSound の出力に適用されるオーディオエフェクト。音声エフェクトの実装
Geometry / Brush / PenBeutl.Media再利用可能な描画ビルディングブロック。(上記の EngineObject パターンを使用)

ライブラリへの登録​

Extension.Load() のオーバーライドで LibraryService を使って型を登録します。

using Beutl.Extensibility;
using Beutl.Graphics.Shapes;
using Beutl.Media;
using Beutl.Services;

namespace MyExtension;

[Export]
public sealed class MyExtension : Extension
{
public override string Name => "My Extension";
public override string DisplayName => "My Extension";

public override void Load()
{
LibraryService.Current.Register<MySampleObject>(
KnownLibraryItemFormats.EngineObject,
"My Sample Object");

LibraryService.Current.AddMultiple("My Object", item => item
.BindGeometry<RectGeometry>()
.BindDrawable<RectShape>());

LibraryService.Current.RegisterGroup("My Extension", group => group
.AddEngineObject<MySampleObject>("My Sample Object")
.AddMultiple("My Shape", item => item.BindDrawable<RectShape>()));
}
}

KnownLibraryItemFormats にはエディタが認識するフォーマット(EngineObject、Drawable、FilterEffect、Brush、Geometry、Pen、Sound、Transform など)の定数が並んでいます。AddMultiple の BindDrawable<T>() ショートカットを使うと、フォーマット文字列を書かずに Drawable を図形ピッカーへ登録できます。

AddDrawable<T>() と AddSound<T>() は EngineObject の形式も登録するようになったため、項目をタイムラインに追加できます。1 つの項目に複数の表現をまとめる場合は、引き続き AddMultiple が使えます。

ソース​