"plug-in-gap-onionskin-configuration"

Onionskin Layers:

  Onionskin Layer(s) usually do show previous (or next) frame(s)
  of the video in the current frame.
  The GIMP Video Menu has a submenu named "Onionskin" that provides
  functions to deal with onionskin layers


  Start from Menu:
       <Image>/Video/Onionskin/Configuration...  

       <Image>/Video/Onionskin/Create or Replace
       <Image>/Video/Onionskin/Delete
       <Image>/Video/Onionskin/Toggle Visibility

  

  Onionskin layers are copies of previous or next frames
  of the video. 
  By default they are built by merging the visible 
  layers of the previous frame but without the BG-Layer 
  (and without other onionlayers).
  Onionskin layers are usually placed above the backroundlayer
  in the layerstack of the current frame.  
  
  Onion Layers are normally used for display of the previous
  scene when painting moving characters.
  They behave like a normal layer, but you can toggle
  visibility or delete onionskin layers
  with Functions provided by this module.
    

Configuration:
  In the onionskin configuration dialog window you can
  - edit the settings for creation of onionskin layers
  - apply the settings to a selected range of frames
  - delete onionskin layers in a selected range of frames.


  Reference Mode:
      NORMAL             /* default */
         The Frame Reference Parameter is used as delta
	 in just one direction.
	 Negative values refere to previous frames only,
	 positive values refere to next frames only.
      BIDRIECTIONAL_SINGLE
         The Frame Reference Parameter is used as 
	 bidirectional delta in both directions
	 With an inital Frame Reference offset -1
	 the reference sequence is
	 -1, +2, -3, +4, -5, +6, ...
	 
      BIDRIECTIONAL_DOUBLE
         The Frame Reference Parameter is used as 
	 bidirectional delta in both directions
	 With an inital Frame Reference offset -1
	 the reference sequence is
	 -1, +1 -2, +2, -3, +3, ...
    
    
  Onionskin Layers:
     Defines how many onionlayers will be created in
     the current image.
         
  Frame Reference:
     Stepsize to reference the source framenumber
     from where we copy the onionlayer.
     Examples:
         -1  .. copy 1.st onionlayer from current framenumber -1
                copy 2.nd onionlayer from current framenumber -2
                
         +2  .. copy 1.st onionlayer from current framenumber +2
                copy 2.nd onionlayer from current framenumber +4

         The example assumes Reference Mode NORMAL.

  Cyclic (Togglebutton):
     Define fold back behavior when referencing previous
     or next frames:
     ON:  last frame has frame 0 as next frame.
     OFF: last frame has NO next frame.

  Stackposition:
     Position where to place onionlayer(s) in the layerstack.

  From TOP (Togglebutton):
         ON: Stackposition is counted from top (0 is on top)
         OFF: Stackposition is counted from bottom (0 is on bottom)

  Opacity:
     The 1.st onionlayer is created with this
     opacity seting (100 is full opaque, 0 is full transparent)

  Opacity Delta:
     100 : The 2.nd onionlayer is created with same
           opacity as the 1.st onionlayer.
     80  : The 2.nd onionlayer is created with 
           80% of the opacity of the 1.st onionlayer,
           The 3.rd with 80% of the 2.nd  and so on...
 
  Ascending Opacity (Togglebutton):
     ON: the farest handled Neighbour Frame has the
         highest Opacity (the Primary Opcaty defined above)
         This may be used to create cross-fading effects.
         (*) see cross-fading example settings below.
             
     OFF: the nearest handled Neighbour Frame has the
          highest Opacity, Opacity is descending
          for the other frames at farer distance.
          This should be used for regular Onionskin usage.

 
  Options how to merge the previous Layer into one Onionlayer:
  
      Restrict by Layernames:  Default '*'  all Names.
         Here you can specify a layernamepattern.
         only layers with matching names are included
         in the onionlayer.
      
      Ignore BottomLayer(s):   Default 1
         Here you can exclude the background layer (1)
         or n layers counted from the bottom of the
         layerstack from the merged copy of the frame
         that makes up the onionlayer.
        
  
  

  
  Auto Create after Load
       ON: Force automatic Creation (or Replacement) of Onionskin Layer(s)
           on GAP controlled Framechanges.
  Auto Delete before Save
       ON: Force automatic Delete of Onionskin Layer(s)
           on GAP controlled Framechanges.

           GAP controlled Framechanges are GoTo Operations in the Video Menu
           or in The Video/VCR Navigator Dialog or in the Video/Playback
           dialogs.




  The Buttons:    

  APPLY:
    The apply button creates onion layers in the selected range
    of frames and sets the values for the handled Animation.

  DELETE:
    The delete button removes onion layers in the selected range
    of frames and sets the values for the handled Animaton.
    

  CLOSE:
    This button Closes the window and sets the values for the current
    handled Animation, without changing any frame.
    
    
  DEFAULT:
    Load hardcoded defaults (does not set anything)
    

  SET for <name_of_the_current_animation>:
    This button sets the values for the current
    handled Animation.




Restrictions:

   - The Onionskin automatic does NOT work if you load a frame
     via the File Menu, or othe implicite file load/save operations.
   
   - Onionskin Layers are restricted to Imagefortmats that can store
     multiple layers, layer parasites and tattoos.

     GIMP's native format XCF is rcommanded.



Onionskin Functions:

  The other functions in the Video/OnionskinLayer menu
  do not open dialog windows. 
  They are intended for quick use, and it is recommanded
  to assign key-shortcuts if you want to use them
  frequently.
  ### here we should refere to gimp docs howto assign key-shortcuts ###
  
  
  Create or Update Onion Layers:
       Create onionlayers in the current frame,
       according to the configurated settings.
       (see above)
  
  Toggle Visibility:
       Turn visibilty on (or off) for all onionlayers.

  Delete Onion Layers:
       Remove all onionlayers from the current frame.
 
       Note: if you made a copy of an onionlayer manually
             the copy should not be deleted.
             If you have gimp-1.2.2 the copy will be deleted too,
             because there is a bug in the gimp video base functions.




Tips:  Cross-Fading Example

   With special Onionskin  Settings you can get Cross Fading Effects.
   
   An animation was created with a Framerate of 8 f/sec
   and should playback on a target rate of 24 f/sec
   
   As 1.st step you need to duplicate all the frames in a way like this:
   
   01  02  03  04 ...            original squence
   
   01  02 03   04 05 06   07 08 09   10 11 12 ....   new numbers
   01  01 01   02 02 02   03 03 03   04 04 04 ....   (old original numbers)
   
   Use the Menu  <Image>/Video/Frames Density... for this task.
   

   To to improve smoothness, you can use Onionskin Layers
   to show 1 and 2 frames ahead on top of the Layerstack.
   
   In The 2.nd Step You create Onionskin Layers in all resulting Frames
   with the following Settings:
   
   Onionskin Layers: 2      Ascending Opacity: ON
   Frame Reference:  1      Cyclic:            OFF
   Stackposition:    0      From Top:          ON
   Opacity:          66.6   50.0
   
   Ignore BG-layer(s): 0        // do not ignore any Layer
   
   From Frame: 1
   To Frame  : the last frame of your animation
  


  When you wan equally balanced Opacity
  you should use Opacity 1/3 for each frame
  33.3 %, 100%
