"plug-in-filter-macro"

Filtermacro Script:

    Start from Menu:

      "<Image>/Filters/Filtermacro"

    WARNINGS:
    - filtermacro scripts are a temporary solution. Support may be removed
      in future releases of gimp-gap. 
    - filtermacros are restricted to plug-ins that are able to run with LAST_VALUES.
    - filtermacro scriptfiles are machine dependent, plug-in version dependent, 
      and may not work in the expected way or even crash at execution on other machines
      or on execution with newer versions of the recorded filter plug-ins.

  Filename:
    Name of the filtermacro scriptfile.

  Delete All button:
    Delete the filtermacro scriptfile.

  Delete button:
    Delete the currently selected filtercall from the filtermacro scriptfile.

  Add
    Add a new filtercall to the filtermacro scriptfile.
    This button opens a PDB browser dialog window,
    where you can select filters that have been already used
    within the current GIMP-session.
    The PDB browser will show only filters that can
    operate on a drawable and have stored the parameters
    of the last run (in the current Session)

  Cancel
    Close the window without any further action.

  OK
    Close the window and apply all the filtercalls
    that are listed in the filtermacro scriptfile
    with their recorded parameters to the
    current drawable.
    (this is the drawable from where the 'Filter Macro' dialog
    was invoked from)


  Recording of a filtermacro will automatically create an additional
  filtermacro reference file in case one of the recorded filters
  has references to additional drawables (e.g. layers).
  One such filter example is the plug_in_bump_map that uses the bumpmap DRAWABLE
  in addition to the processed input drawable.
   
   
  A filtermacro reference file has the same name as the filtermacro scriptfile
  with extension .fmref
  This file records filename, type and position of such additional drawables
  to allow applying the filtermacro in another gimp session.
  
  Currently supported types are: 
  - 3: GAP_AINFO_ANIMIMAGE  layer in a multilayer image,
  - 4: GAP_AINFO_FRAMES:    frame (flattened representation in a sequence of numbered images)
  - 5: GAP_AINFO_MOVIE:     and movie (frame extracted from a videofile)
  
  Where the type is automatically detected at recording like this:

  - In case the drawable is the layer of an image that was extracted from a videofile
    within the same GIMP-session
    (by click on the GAP Playback dialog preview) 
    the type 5: GAP_AINFO_MOVIE is recorded.
    Such layers are marked (with a non-persistent layer parasite)
    at extraction time to provide videofilename and position in the video.
  
  - In case the drawable is a layer in an image with GIMP-GAP typical number part
    and another frame image with next or previous number is already existent
    the type 4: GAP_AINFO_FRAMES is assumed.
    
  - All other cases use type 3: GAP_AINFO_ANIMIMAGE .
  
  Restrictions:
  -------------
  - Note that persistent drawable references will NOT work or give unexpected
    results in case the image that contains the referred drawable
    was not saved, or was changed and saved after the filtermacro was recorded.
  - Furthermore the filter must use the GIMP-GAP standard iterator implementation
    that supports the recording of persistent drawable id's for its additional
    drawable parameters.



  Tip:
  Filtermacro execution can be used in the same way as a single
  filtercall, together with the
    'Filter All Layers'  and the 
    'Frames Modify 
  features of gimp-gap. This way you can apply a set of filtercalls
  on all layers of a multilayer image
  (or on all selected layers in multiple frames) with one call.
  
  Filtermacro file execution is also available in Storyboard scripts.
  See STORYBOARD_FILE_DOC.txt chapter Macrofiles for more details.
