paint.net 'WEBP Animations and Images' FileType Plugin (.AWEBP)

+-------------------------------------------------------------------------------
| Summary
+-------------------------------------------------------------------------------
Loads and saves WEBP animations and images. 

Animated images contain a sequence of images called frames which a viewer 
application can show as an animation.

Because paint.net decides on the file extension which file loader will be used 
you have to change the extension of the WEBP file to .awebp. 

On load the plugin loads all frames from the file and adds them as layers to a 
new Paint.NET document. Frame 1 will become the bottom layer and so on. Some
information from the file (like frame durations or comments) will be stored
in the layer names after the marker '//'.

On save the plugin will convert all layers to frames respecting the information
found after the marker '//' in the layer names. The plugin does its best to 
reduce the size of the final file. The size depends on various settings.
WebP supports an alpha channel, lossless and loosy compression, and true color.

This plugin never preserves existing metadata (EXIF, XMP, ICCP) but may add 
its own EXIF metadata (comments, resolution). 

Animated WEBP file format restrictions
- maximum value of width and height is 16383 pixels
- the progress view in lossless encoding is limited

Together with the 'GIF Animations and Images' FileType Plugin you can convert
from animated GIF to WEBP and vice versa.

+-------------------------------------------------------------------------------
| Author / Copyright
+-------------------------------------------------------------------------------
Martin Osieka
2021-2022, Martin Osieka, Switzerland
You may use this plugin together with Paint.NET w/o any restriction.

+-------------------------------------------------------------------------------
| Installation
+-------------------------------------------------------------------------------
Follow the instructions carefully
- Unzip the archive
- Copy the folder ImAWEBP.FileType together with its content (ImAWEBP.FileType.dll
  /.dlc/.deps.json) into the FileTypes folder of paint.net. The location of the 
  FileTypes folder depends on the installed variant of paint.net.
To verify the installation you should restart Paint.NET and check that in the 
filetype popup of the open file selector dialog is an entry starting with AWEBP.

+-------------------------------------------------------------------------------
| Compatibility
+-------------------------------------------------------------------------------
paint.net >= 4.3.2, 64bit and 32bit

+-------------------------------------------------------------------------------
| Supported languages
+-------------------------------------------------------------------------------
English, Deutsch
You may add your own translation to the .dlc file.

+-------------------------------------------------------------------------------
| Keywords
+-------------------------------------------------------------------------------
FileType, WEBP, AWEBP, Animation

+-------------------------------------------------------------------------------
| Dialog Options
+-------------------------------------------------------------------------------

The save dialog allows you to select the file variant to create: 
- WEBP Animation
- WEBP Image

Preview button: Only enabled if the file variant is WEBP Animation.
Creates a temporary file containing the animation and plays the file in
a preview window. Right click the preview window to get a context menu
containing several commands.

Suppress metadata: If this option is checked then no metadata will be
written to the file (no Exif, XMP, or ICC profile). 

Image category: Select the basic category of the image. This allows the
encoder to optimize the quality of the image,

Encoding: You may select lossless and loosy endcoding.
In the lossless case the slider has impact to the speed of the encoding
and the final file size (100 means slowest encoding but smallest size).
Loosy encoding can reduce the final file size drastically. But a smaller
file size means a lower quality (100 means best quality but biggest size).

Depending on the variant you can define some initial settings in the dialog.
Initial means that they will be redefined if the related commands are used in 
the layer names.

Comment: see Comment=
Maximum number of colors: see MaxColors=
Frame duration: see Duration=
Cycles: see Cycles=
Remove duplicates of frames: see NoDups=

+-------------------------------------------------------------------------------
| Layer names commands
+-------------------------------------------------------------------------------

Commands with preset in the save dialog:
  Comment=A;  
    ASCII text only. Use this to add the crator of the file or other info.
  Duration=N; or N ms;  or M fps;
    Display time in milliseconds. You may also use fps (frames per seconds) 
	which will be mapped to a duration (duration = 1000 ms / M)
  Cycles=N;
    The number of cycles the animation should be played by a viewer application.
	The viewer may ignore this value. The default value is 0, which means infinite.
  NoDups=B
    true: if the successor of a frame is a duplicate then this duplicate will be 
	  removed and its duration will be added to the duration of the frame
	false: no action
	The default value is true

Commands to define how the layer content will be used:
  UseAsBackground;
    Set this background for all following frames up to the next background command.
	UseAsBackground=false; means that the following frames do not use a background
  UseAsForeground;
    Set this foreground for all preciding frames up to a previous background command.
	UseAsForeground=false; means that the preciding frames do not use a foreground
  UseAsNote;
    Ignore layer. The layer may be used to draw help lines.
  UseAsDefault;
    Set the image in the layer as default image. Used if the viewer does not support
	animations. Has no effect in WEBPs, will be handled like UseAsNote.
  UseAsSprite=NAME,ORIGINX,ORIGINY,BOUNDSX,BOUNDSY,BOUNDSW,BOUNDSH;
    Defines the layer content as a sprite with the name NAME.
    A sprite layer can be at any position in the layer stack. 
	It can be referenced from other commands via NAME.
    Sprite names are not case-sensitive and must be unique. Don't use
    whitespace or any delimiters in the names.
    ORIGINX and ORIGINY are optional coordinates of the sprite origin (default 0,0).
    BOUNDSX, BOUNDSY, BOUNDSW, and BOUNDSH define location and dimensions of the
    sprite (default layer bounds).
  
Other commands
  Draw=NAME,X,Y;
    Draws the sprite NAME to the frame generated from the current layer.
	By default the origin of the sprite will be drawn at the origin of the layer.
	But you can can use the optional parameters X and Y to move the draw position.
    Multiple 'draw' commands are allowed in a layer name.
    The sprite layer should be transparent because the content will be blended
    on top of the current layer.
  Tile=NAME,X,Y;
    Like Draw but tiles the complete layer with the sprite. This is useful if you
    like to animate a pattern which should repeat.
  Transition=T,V,D;  
    Adding a transition command means that additonal frames will be generated 
    in-between the current frame and the next one. The content of these frames
    depends on the transition type T an optional direction D and variant V.
    Direction D may be: left, top, right, bottom, topleft, topright, bottomleft, 
    bottomright, center. Variant V may be: normal, zoom, hor, ver. 
    Not all types support all directions or variants.
    The following transitions are available:
	  Fade
	    Alpha blends the current frame with the next frame (no direction or variant)
      Push,D      
	    Moves the previous and the next frame in direction D
      Cover,D,V
	    Covers the previous image with the next image by moving 
        next image in direction D. V variant (normal,zoom,hor,ver)
      Uncover,D,V
	    Uncovers the next image by moving the previous image in 
        direction D using variant V
      WipeIn,D,V
      WipeOut,D,V
      Blinds,D
	    D may be hor or ver
  Duplicate=N,M;
	Duplicates the last N frames sequence M times. M is optional (default is 1)
  Reverse=N;          
    Adds N frames generated up to the current layer in reverse 
    order to the animation (not including the first and the current frame). I.e. if 
    layer 5 has the reverse setting then you will get the frames 1 2 3 4 5 4 3 2.
    N is optional. If not given the revers to the first frame.

+-------------------------------------------------------------------------------
| How-to
+-------------------------------------------------------------------------------

Create a new animated WEBP:
. Select File->New
- Add as many layers as you like. Use layer properties to add settings after '//' 
  to the layer names. I.e. add "// 2000 ms" to the bottom layer name.
- Select Menu->Save As...
- In the 'Save As' dialog select 'AWEBP' as file type and enter a name. 
- Select OK in the save dialog.
- In Windows FileExplorer change the extension of the new file from '.awebp' to '.webp'.

Edit an animated WEBP: 
- In Windows FileExplorer change the extension of the file from '.webp' to '.awebp'
- Open the file in Paint.NET
- Continue as in 'Create a new animated WEBP'

+-------------------------------------------------------------------------------
| How does save works
+-------------------------------------------------------------------------------
Saving of an animated WEBP is a complex process (compared to other file types)
because the image data has to be processed to create new images. Here are
the steps needed to create the file:
- Analyze all layer names and extract the settings
  (the visibility property of a layer has no impact to this procedure)
- Create a list of frame images from the layers by merging the layers.
  next frame = 
      'UseAsBackground' layer (if defined)
	 + next layer
	 + 'UseAsSprite' layers which should be drawn to this layer
	 + 'UseAsForeground' layer (if defined)
  This process respects opacity and blend mode properties of the layers.
- Transition commands may create additional frames between the normal ones.
- Remove duplicate frames by adding their duration to their predecessor.
- Calculate a good disposal strategy used to store a frame in minimal size.
  This is a heuristic method. It is not possible to calculate always the best.
- Store the frames in the file. Add the delays and comments information.

+-------------------------------------------------------------------------------
| History
+-------------------------------------------------------------------------------
1.4 [2022-01-24]
- Fixed a bug in TransitionFade in case the final frame is transparent
- Remove duplicates from frames is now always true and disabled because the
  WebPEndoder will do this in all cases.
1.3 [2022-01-20]
- Updated to use libwebp 1.2.2 (x64, x86) (contains the bug fix for progress values > 100%)
  There is still the libwebp issue that the progress reporting in the lossless case is limited 
1.2 [2022-01-15]
- Improved saving of still images
- Added option to suppress saving of any metadata
- Provided better progress info during save
- Changed Exif handling
- Reworked transitions handling
1.1 [2022-01-06]
- Added Save functionality including preview
1.0 [2021-12-26]
- Initial version based on libwebp 1.2.1 (x64, x86). Load only!
