From 69462e3333737bd8c1a625c8e72127e388f0da80 Mon Sep 17 00:00:00 2001 From: Yuto Terada Date: Sun, 29 Dec 2024 00:19:15 +0900 Subject: [PATCH] update (en) --- en/advanced/2.source-operator.md | 10 +-- en/advanced/4.render-cache.md | 64 ++++++------------- en/extensions/2.create-csproj.md | 18 +++--- en/extensions/3.available-extensions.md | 2 +- en/extensions/implement-drawing-object.md | 77 +++++++---------------- en/extensions/implement-effect.md | 40 ++++++------ en/extensions/version-mapping.md | 21 ++++--- en/get-started/1.install.md | 47 +++++++------- en/get-started/5.edit-element.md | 50 +++++++++------ en/get-started/7.encode.md | 14 +++-- en/get-started/8.notes.md | 22 +++---- 11 files changed, 160 insertions(+), 205 deletions(-) diff --git a/en/advanced/2.source-operator.md b/en/advanced/2.source-operator.md index 7ae88e3..2c88c9d 100644 --- a/en/advanced/2.source-operator.md +++ b/en/advanced/2.source-operator.md @@ -3,12 +3,4 @@ title: Source Operations description: Explanation of the types of source operations --- -There are mainly two types of source operations. - -**Publisher** -- Issues drawing objects such as shapes, images, and videos with specified properties. -- Retrieves elements below the current layer and issues their drawing objects. - -**Transformer** -- Modifies drawing objects issued by the Publisher. -- Wraps drawing objects issued by the Publisher with newly created drawing objects. \ No newline at end of file +Obsolete \ No newline at end of file diff --git a/en/advanced/4.render-cache.md b/en/advanced/4.render-cache.md index a4a1e2e..bb29923 100644 --- a/en/advanced/4.render-cache.md +++ b/en/advanced/4.render-cache.md @@ -1,56 +1,28 @@ --- -title: Caching -description: Explanation of the criteria for generating drawing caches in Beutl +title: Cache +description: Explanation of render cache generation in Beutl --- ## Cache -Consider the following nodes: +Consider the following nodes. ``` -1. Drawing Node +1. Render Node 2. └ Transform Node -3. 　 └ Effect Node -4. 　 　 └ Shape Node +3. 　 └ Effect Node (Drop Shadow, with animation) +4. 　 　 └ Effect Node (Outline) +5. 　 　 　 └ Shape Node ``` -Within the Effect Node: -``` -3-1. Border -3-2. DropShadow (with animation) -``` -The Transform Node and Shape Node do not have animation. - -In conclusion, in this example, after a few frames are drawn, Beutl caches up to 3-1 within the Effect Node. -The reasoning behind this is explained below. - -## Determining Cache Eligibility -Beutl determines that caching is possible if the state remains the same for three or more frames. - -There are two methods for counting frames: -1. Automatic Counting - This method requires that the node remains unchanged, but it is very simple. - The frame count increments during rendering, and resets to zero if the node changes. - If the count reaches 3 or more, the node is deemed **cacheable**. - -2. Manual Counting - This method applies to nodes implementing `ISupportRenderCache`. - These nodes report how much remained the same compared to the previous frame. - If the minimum value of the similarity over the last three frames is 1 or more, the node is deemed **cache-boundary eligible**. - If all three frames are the same, the node is deemed **cacheable**. -``` - -> Frames - 1 2 3 4 -3-1. ■ ■ ■ ■ -3-2. ○ ● ○ ● -``` -In this case, the second frame and beyond would report `1/2`. - -After the fourth frame is rendered, the node is deemed **cache-boundary eligible**. -> [!NOTE] -> **Nodes that are ancestors of a cache-boundary node cannot be cached.** - -If a node is deemed **cache-boundary eligible** or **cacheable** and all its child nodes are **cacheable**, the drawing content of that node is cached. +Transform Node and Shape Node have no animation. -### Manual Control with ISupportRenderCache +In conclusion, +In this example, after a few frames are rendered, +Beutl will cache up to the 4th effect node. +Below is an explanation of why this happens. -Nodes implementing `ISupportRenderCache` can manually control whether to cache, the process of saving the cache, and rendering using the cache. +## Determining Cacheability +If the same state persists for 3 or more frames, it is considered cacheable. +During node rendering, a count is maintained, and if the node changes, the count is reset to zero. +When this count reaches 3 or more, it is considered **cacheable**. -This implementation allows partial caching of multiple effects, and is used within the Effect Node. +If a node is **cacheable** and all its child elements are **cacheable**, +the rendering content of that node is cached. diff --git a/en/extensions/2.create-csproj.md b/en/extensions/2.create-csproj.md index 0f1f6f9..b666ece 100644 --- a/en/extensions/2.create-csproj.md +++ b/en/extensions/2.create-csproj.md @@ -6,7 +6,7 @@ description: Explanation of how to create an empty C# project for Beutl extensio This article explains how to create an empty C# project for Beutl extensions. This guide introduces the methods using __Visual Studio Code__ or __Visual Studio__. -The target Beutl version is `1.0.0-preview.6`. +The target Beutl version is `1.0.0-preview.11`. ## Visual Studio Code 1. Use the terminal to create a class library. @@ -28,7 +28,7 @@ MyBeutlExtension - net8.0 + net9.0 enable enable @@ -52,9 +52,9 @@ MyBeutlExtension - - - + + + @@ -98,7 +98,7 @@ MyBeutlExtension - net8.0 + net9.0 enable enable @@ -122,9 +122,9 @@ MyBeutlExtension - - - + + + diff --git a/en/extensions/3.available-extensions.md b/en/extensions/3.available-extensions.md index 0bc04fe..01531d1 100644 --- a/en/extensions/3.available-extensions.md +++ b/en/extensions/3.available-extensions.md @@ -12,7 +12,7 @@ In Beutl, you can extend the following functionalities: | EditorExtension | Adds a UI for editing files | | OutputExtension | Adds a UI for output | | [Extension](sample-extensions.md#sugarshaker) | Base class for extensions (override the Load method to register functionalities) | -| PageExtension | Adds pages that can be selected from the menu on the left side of the window | +| PageExtension | Adds a dialog that can be opened from the Window menu | | ProjectItemExtension | Adds types of items to the project | | PropertyEditorExtension | Adds a UI for editing specific property types | | [ToolTabExtension](sample-extensions.md#ToolTabExtension) | Adds tabs to the scene editing screen | diff --git a/en/extensions/implement-drawing-object.md b/en/extensions/implement-drawing-object.md index d3e39d2..64585ad 100644 --- a/en/extensions/implement-drawing-object.md +++ b/en/extensions/implement-drawing-object.md @@ -18,6 +18,7 @@ Create a `StarShape` class that inherits from the `Drawable` class as follows. ```cs using Beutl.Graphics; +using Beutl.Graphics.Rendering; namespace MyExtension; @@ -29,7 +30,7 @@ public class StarShape : Drawable throw new NotImplementedException(); } - protected override void OnDraw(ICanvas canvas) + protected override void OnDraw(GraphicsContext2D context) { throw new NotImplementedException(); } @@ -112,10 +113,10 @@ public class StarShape : Drawable return _geometry.Bounds.Size; } - protected override void OnDraw(ICanvas canvas) + protected override void OnDraw(GraphicsContext2D context) { // Fill is defined in the Drawable class - canvas.DrawGeometry(_geometry, Fill, null); + context.DrawGeometry(_geometry, Fill, null); } } ``` @@ -127,6 +128,7 @@ Test if the star shape is drawn correctly. ```cs using Beutl.Media; using Beutl.Graphics; +using Beutl.Graphics.Rendering; using MyExtension; var shape = new StarShape() @@ -135,10 +137,11 @@ var shape = new StarShape() Fill = Brushes.White }; -using var canvas = new ImmediateCanvas(120, 120); -shape.Render(canvas); +using var renderTarget = RenderTarget.Create(120, 120); +using var canvas = new ImmediateCanvas(renderTarget); +canvas.DrawDrawable(shape); -using var bitmap = canvas.Snapshot(); +using var bitmap = renderTarget.Snapshot(); bitmap.Save("star.png"); ``` @@ -146,37 +149,6 @@ Run the following command to generate the image: ```sh dotnet run -p:OutputType=Exe ``` -
-If you want to use effects and draw in the console - -```cs -using Beutl.Media; -using Beutl.Graphics; -using Beutl.Graphics.Rendering; -using MyExtension; - -var shape = new StarShape() -{ - Size = 100, - Fill = Brushes.White -}; - -var canvasSize = new PixelSize(120, 120); -var node = new ContainerNode(); -using (var deferred = new DeferredCanvas(node, canvasSize)) -{ - shape.Render(deferred); -} -// Use using (...) { ... } or the Dispose method before rendering the node. - -using var canvas = new ImmediateCanvas(canvasSize.Width, canvasSize.Height); -node.Render(canvas); - -using var bitmap = canvas.Snapshot(); -bitmap.Save("star.png"); -``` - -
## 2. Create the SourceOperator Class @@ -187,28 +159,21 @@ using Beutl.Operators.Source; using Beutl.Graphics.Effects; using Beutl.Graphics.Transformation; using Beutl.Media; -using Beutl.Styling; namespace MyExtension; -public class StarShapeOperator : DrawablePublishOperator -{ - public Setter Size { get; set; } = new(StarShape.SizeProperty, 100); - - public Setter Transform { get; set; } = new(Drawable.TransformProperty, new TransformGroup()); - - public Setter AlignmentX { get; set; } = new(Drawable.AlignmentXProperty, Media.AlignmentX.Center); - - public Setter AlignmentY { get; set; } = new(Drawable.AlignmentYProperty, Media.AlignmentY.Center); - - public Setter TransformOrigin { get; set; } = new(Drawable.TransformOriginProperty, RelativePoint.Center); - - public Setter Fill { get; set; } = new(Drawable.FillProperty, new SolidColorBrush(Colors.White)); - - public Setter FilterEffect { get; set; } = new(Drawable.FilterEffectProperty, new FilterEffectGroup()); - - public Setter BlendMode { get; set; } = new(Drawable.BlendModeProperty, Graphics.BlendMode.SrcOver); -} +public class StarShapeOperator() : PublishOperator( +[ + (StarShape.WidthProperty, 100), + (Drawable.TransformProperty, () => new TransformGroup()), + Drawable.AlignmentXProperty, + Drawable.AlignmentYProperty, + Drawable.TransformOriginProperty, + (Drawable.FillProperty, () => new SolidColorBrush(Colors.White)), + (Drawable.FilterEffectProperty, () => new FilterEffectGroup()), + Drawable.BlendModeProperty, + Drawable.OpacityProperty +]); ``` ## 3. Create the Extension Class diff --git a/en/extensions/implement-effect.md b/en/extensions/implement-effect.md index 15ff160..d91f32e 100644 --- a/en/extensions/implement-effect.md +++ b/en/extensions/implement-effect.md @@ -71,35 +71,39 @@ public class MyFilterEffect : FilterEffect public override void ApplyTo(FilterEffectContext context) { // The data argument is passed to the action and transformBounds methods - // Specify a comparable value - context.Custom( + // Specify an equivalence-comparable value + context.CustomTom( data: 0, action: CustomEffectProcess, transformBounds: (_, b) => b); } - private static void CustomEffectProcess(int _, FilterEffectCustonOperationContext context) + private static void CustomEffectProcess(int _, CustomFilterEffectContext context) { - // Obtain SKSurface - if (context.Target.Surface is { } surface) + for (int i = 0; i < context.Targets.Count; i++) { - // Use SKCanvas + EffectTarget target = context.Targets[i]; + RenderTarget renderTarget = target.RenderTarget!; + // When operating Skia directly + // 1. Get SKSurface + SKSurface surface = RenderTarget.GetSKSurface(renderTarget); + // 2. Get SKCanvas SKCanvas skcanvas = surface.Value.Canvas; + // 3. Manipulate skcanvas.Clear(); - } - // Use Beutl's canvas - using (ImmediateCanvas canvas = context.Open(context.Target)) - { - canvas.Clear(); - } + // When using the Beutl wrapper + // 1. Create Canvas + using (var canvas = new ImmediateCanvas(renderTarget)) + { + // 2. Manipulate + canvas.Clear(); + } - // Replace the effect target - // (Change the image processed by subsequent effects) - // Using a reference counter, hence using 'using'. - using (var newTarget = context.CreateTarget(width: 100, height: 100)) - { - context.ReplaceTarget(newTarget); + // If you want to change the image size + var newTarget = context.CreateTarget(width: 100, height: 100); + context.Targets[i] = newTarget; + target.Dispose(); } } } diff --git a/en/extensions/version-mapping.md b/en/extensions/version-mapping.md index 0dcce5c..9b3bee3 100644 --- a/en/extensions/version-mapping.md +++ b/en/extensions/version-mapping.md @@ -5,11 +5,16 @@ description: List of Beutl versions and their corresponding dependencies, framew This table lists the versions of Beutl along with their corresponding dependencies, frameworks, and library versions. -| Beutl | .NET | [Avalonia](https://github.com/AvaloniaUI/Avalonia) | FFmpeg | -| --------------- | ---- | -------------------------------------------------- | ------ | -| 1.0.0-preview.6 | 8.0 | 11.0.10 | 6.0 | -| 1.0.0-preview.5 | 8.0 | 11.0.9 | 6.0 | -| 1.0.0-preview.4 | 8.0 | 11.0.5 | 6.0 | -| 1.0.0-preview.3 | 7.0 | 11.0.4 | 6.0 | -| 1.0.0-preview.2 | 7.0 | 11.0.4 | 6.0 | -| 1.0.0-preview.1 | 7.0 | 11.0.4 | 6.0 | \ No newline at end of file +| Beutl | .NET | [Avalonia](https://github.com/AvaloniaUI/Avalonia) | FFmpeg | +| ---------------- | ---- | -------------------------------------------------- | ------ | +| 1.0.0-preview.11 | 9.0 | 11.1.3 | 6.0 | +| 1.0.0-preview.10 | 8.0 | 11.1.3 | 6.0 | +| 1.0.0-preview.9 | 8.0 | 11.1.3 | 6.0 | +| 1.0.0-preview.8 | 8.0 | 11.0.11 | 6.0 | +| 1.0.0-preview.7 | 8.0 | 11.0.10 | 6.0 | +| 1.0.0-preview.6 | 8.0 | 11.0.10 | 6.0 | +| 1.0.0-preview.5 | 8.0 | 11.0.9 | 6.0 | +| 1.0.0-preview.4 | 8.0 | 11.0.5 | 6.0 | +| 1.0.0-preview.3 | 7.0 | 11.0.4 | 6.0 | +| 1.0.0-preview.2 | 7.0 | 11.0.4 | 6.0 | +| 1.0.0-preview.1 | 7.0 | 11.0.4 | 6.0 | \ No newline at end of file diff --git a/en/get-started/1.install.md b/en/get-started/1.install.md index 50700cc..4266100 100644 --- a/en/get-started/1.install.md +++ b/en/get-started/1.install.md @@ -1,65 +1,70 @@ --- title: Installation -description: Instructions on how to install Beutl +description: How to install Beutl --- This document explains how to install Beutl. -The version of Beutl being installed in this document is referred to as `{version}`. +In this document, the version of Beutl to be installed is referred to as `{version}`. -## Prerequisites -Install [.NET 8](https://dotnet.microsoft.com/ja-jp/download/dotnet/8.0). +## For Windows + +### Using the standalone installer (recommended) +1. Download and run `beutl-standalone-setup.exe`. +2. Follow the on-screen instructions to install. +3. Refer to [FFmpeg Installation](../ffmpeg-install.md) to install FFmpeg. +4. Launch `Beutl.exe`. + +### Using the lightweight installer +Install the [.NET Runtime](https://dotnet.microsoft.com/download/dotnet/9.0). > [!TIP] -> Determine the version of .NET to install based on the version of Beutl. +> Determine the version of .NET to install based on the version of Beutl you are installing. > [Version Compatibility Table](../extensions/version-mapping.md) -## For Windows - -### Using the Installer 1. Download and run `beutl-setup.exe`. 2. Follow the on-screen instructions to install. -3. Refer to [Installing FFmpeg](../ffmpeg-install.md) to install FFmpeg. +3. Refer to [FFmpeg Installation](../ffmpeg-install.md) to install FFmpeg. 4. Launch `Beutl.exe`. -### Manual Installation -1. Download and extract `beutl-win-x64-{version}.zip`. -2. Refer to [Installing FFmpeg](../ffmpeg-install.md) to install FFmpeg. +### Manual installation +1. Download and extract `beutl-win-x64-standalone-{version}.zip`. +2. Refer to [FFmpeg Installation](../ffmpeg-install.md) to install FFmpeg. 3. Launch `Beutl.exe`. ## For Ubuntu 22.04 -### Installing from Debian Package +### Installing from Debian package > [!TIP] > This method is available from `1.0.0-preview.5`. 1. Download `beutl_1.0.0-285ubuntu22.04_amd64.deb`. -2. Execute the following commands: +2. Run the following commands: ```sh sudo apt update sudo apt install ./beutl_1.0.0-285ubuntu22.04_amd64.deb ``` 3. Installation is complete. -### Manual Installation -1. Download and extract `beutl-linux-x64-{version}.zip`. -2. Refer to [Installing FFmpeg](ffmpeg-install.md) to install FFmpeg. +### Manual installation +1. Download and extract `beutl-linux-x64-standalone-{version}.zip`. +2. Refer to [FFmpeg Installation](ffmpeg-install.md) to install FFmpeg. 3. Use `chmod` to make `Beutl`, `Beutl.ExceptionHandler`, `Beutl.PackageTools`, and `Beutl.WaitingDialog` executable. 4. Launch `Beutl`. > [!IMPORTANT] -> If installing a version prior to `1.0.0-preview.5`, +> If installing a version below `1.0.0-preview.5`, > refer to [this guide](https://github.com/shimat/opencvsharp#ubuntu) to build `libOpenCvSharpExtern`. ## For macOS -Download and extract either `Beutl.osx_arm64.app.zip` or `Beutl.osx_x64.app.zip`. -You may see a warning like the one below. +Download and extract `Beutl.osx_arm64.app.zip` or `Beutl.osx_x64.app.zip`. +You should see a warning like this: ![](./_images/1.install/macos-gatekeeper.jpg) This warning appears because I have not signed the application. -To bypass this warning, execute the following command: +To bypass this, run the following command: ```sh xattr -rc Beutl.app ``` diff --git a/en/get-started/5.edit-element.md b/en/get-started/5.edit-element.md index bcd644c..b91c14f 100644 --- a/en/get-started/5.edit-element.md +++ b/en/get-started/5.edit-element.md @@ -1,54 +1,64 @@ --- title: Editing Elements -description: Explains how to add effects, move elements, and more in Beutl +description: Explains how to add effects to elements, move them, and more --- -This document explains how to add effects, move elements, and perform other editing tasks in Beutl. +This page explains how to add effects to elements, move them, and more. -## Basic Knowledge +## Prerequisite Knowledge -This page uses terms such as __Source Operations__ and __Drawing Objects__. For more details, please refer to [this document](../advanced/1.rendering-process.md). +This page uses terms such as __Source Operation__ and __Drawing Object__. +For details, please refer to [here](../advanced/1.rendering-process.md).
-How to identify in the UI +How to distinguish on the UI -How to identify in the UI +How to distinguish on the UI
## Adding Effects -First, select the element you want to add an effect to on the timeline. The properties of the selected element will be displayed in the __Source Operations__ tab on the right side. +First, select the element you want to add on the timeline. +The properties of the selected element will be displayed in the __Source Operation__ tab on the right. -To add an effect directly to a drawing object, click the `+` button in __Filter Effects__ and choose the effect you want to add. +To add an effect directly to a drawing object, +click the `+` button in __Filter Effects__ and select the effect you want to add. ![](_images/5.edit-element/add-effect-in-property-editor.mp4) Alternatively, you can drag and drop the effect you want to add from the library to __Filter Effects__. ![](_images/5.edit-element/add-effect-via-library.mp4) -Dragging and dropping elsewhere will add the effect as a source operation. +If you drag and drop it elsewhere, you can add the effect as a source operation. ![](_images/5.edit-element/add-effect-as-source-operator.mp4) -## Transformations -Using transformations, you can express movement, rotation, scaling, distortion, and more. +## Transform +Using transform, you can express movement, rotation, scaling, distortion, and more. -To set a transformation directly on a drawing object, click the `+` button in __Transform__ and choose the type of transformation you want to add. +To set a transform directly on a drawing object, +click the `+` button in __Transform__ and select the type of transform you want to add. -For the move transformation only, you can move it with the mouse from the preview screen. However, move transformations added as effects (or source operations) cannot be moved with the mouse. +Only for move transform, you can move it with the mouse from the preview screen. +However, move transforms added as effects (or source operations) cannot be moved with the mouse. ![](_images/5.edit-element/add-transform.mp4) -## Editing Element Timing -You can edit the start time and duration of elements by dragging them with the mouse on the timeline. +## Editing Element Time +By dragging with the mouse on the timeline, +you can edit the start time and duration of elements. -To simplify editing in Beutl, elements will snap to the timing of other layers during dragging. To temporarily disable this feature, hold down the `Alt` key while dragging. This feature __cannot be permanently disabled__ in the settings. +To make editing easier in Beutl, elements snap to the time of other layers during drag operations. +To temporarily disable this, drag while holding down the `Alt` key. +This feature __cannot be permanently disabled__ in the settings screen. ![](_images/5.edit-element/move-element.mp4) ## Splitting Elements -You can split elements by right-clicking the element you want to split on the timeline and clicking the split button in the menu. You can also use the `Ctrl + K` shortcut to split the selected element at the current frame. +Right-click the element you want to split on the timeline and click the split button in the menu to split the element. +You can also use the `Ctrl + K` shortcut to split the selected element at the current frame. ![Splitting Elements](_images/5.edit-element/split-element.webp) -## Making Elements Easier to Identify -In Beutl, you can change the color and name of elements. These can be changed from the right-click menu. +## Renaming Elements +In Beutl, you can change the color and name of elements, +both of which can be changed from the right-click menu. -You can change the name by pressing the `F2` key or double-clicking the element. +You can change the name with the `F2` key or by double-clicking the element. diff --git a/en/get-started/7.encode.md b/en/get-started/7.encode.md index d53fbef..b6ba068 100644 --- a/en/get-started/7.encode.md +++ b/en/get-started/7.encode.md @@ -1,13 +1,15 @@ --- title: Encoding -description: How to export a project created in Beutl to a video file +description: Explains how to export a project created in Beutl to a video file --- > [!NOTE] -> This section is under construction +> Work in progress -This document explains how to export a project created in Beutl to a video file. +This page explains how to export a project created in Beutl to a video file. -1. Open the output page from the left navigation. -2. Click __Add__ in the __Queue__ section. -3. Select the scene you want to export. \ No newline at end of file +1. Click __View > Tools > Output__. +2. The export settings tab will open. +3. Select the file to save. +4. Specify the encoder and change the detailed settings if necessary. +5. Click the encode button. \ No newline at end of file diff --git a/en/get-started/8.notes.md b/en/get-started/8.notes.md index 89a8332..c014097 100644 --- a/en/get-started/8.notes.md +++ b/en/get-started/8.notes.md @@ -1,22 +1,22 @@ --- -title: Important Notes -description: Important notes for using Beutl +title: Notes +description: Explains the notes for using Beutl --- -The important notes explained here are as of `v1.0.0-preview.6`. +The notes explained here are as of `v1.0.0-preview.11`. They may be improved in future updates. -## Manual Saving +## Manual Save > [!TIP] -> Auto-saving is supported from `1.0.0-preview.5`. +> Auto-save is supported from `1.0.0-preview.5`. -~~Beutl does not display a confirmation dialog to save when closing a project or window. -Also, there is no auto-save feature for projects. -Please remember to save manually regularly.~~ +~~Beutl does not display a confirmation dialog when closing projects or windows. +Also, there is no automatic project saving feature. +Please make sure to save manually on a regular basis.~~ -## Extension Security +## Security of Extensions Anyone can publish extensions if they create an account in Beutl. -Therefore, there is a possibility of malicious extensions being included. -Please be cautious. +Therefore, there is a possibility that malicious extensions may be included. +Please be careful. If you find any potentially malicious extensions, please contact us at the following address: contact@mail.beditor.net \ No newline at end of file