"plug-in-gap-move-path"

Move Path (make things move)

      Start from Menu:
          (<Image>/Video/Move Path)


      For this plug-in you need a series of frames (destination video frames)
      and one single image or another series of frames. (source object or moving object)
      If you use a single image as source object all the layers in it
      can be used as source frames.
      
      The source frames are copied into the destination frames.
      Those copies can be transformed in many ways, using controlpoints
      and appears as one new layer in each handled destination frame.
      The X/Y controlpoint coordinates affects the offest of the copied new layer
      in the destination frame(s). All controlpoints build up a path
      that defines how the copied new layer moves within the destination frames.

      Preconditions:      

      - The source image must be opened in the GIMP
      - The source image must be another Image than the destination frame
        (if you really want to copy layers from destination frame
         to destination frame(s) you have to duplicate it first)
      - The source image must be from the same type (RGB, INDEXED ..) as
        the destination frame.

        In other words: To run the 'Move Path' plug-in you have to open at
                        least 2 images of the same type.      
      
      
            
      The selected layer(s) of the source image or frame 
         is (are) copied into the selected range of frames.
         Each handled frame receives exactly one copy of the selected layer
         from the source image, where the copy will be modified by
         transformations such as scaling, changing transparency and more,
         according to the controlpoint settings.
         
      If you use stepmodes "Loop", "Loop Reverse", "Once", "OnceReverse" or "PingPong"
        the layers of the source image are stepped through,
        and the next handled frame receives the next
        layer from the source image's layerstack.
        Note that stepping through the layerstack is resticted to the group
        level of the initally selected source layer.
        In case you selected a source layer that is not inside any layergroup,
        then stepping will not step into layergroups and subgroups, but will pick the
        grouplayers on imagelevel and use them as if all the layers within the group 
        were merged to a single layer.
        
        
        For the frame based stepmodes ("Frame Loop", "Frame PingPong" ...)
        the selected source(layer) should be a layer of another video frame.
        In the frame based stepmodes the source object is considered
        as video frames and stepping is done from frame image to the next frame image
        (and not from layer to layer)
        The inserted layer is always a copy of one frame of the
        source object animation (no matter which source layer was selected)
        where all the visible source layers are merged to build up the moving object.
        

	
	If you use a normal image (that is not a video frame with typical framenumber in its filename) as source
	for the frame based stepmodes it acts like an animation with 
	only one frame.
        
      The "Step Speed" factor
        decides how fast to step through the source object,
        in relation to the target frames. 
        With factor 1.0 source and target will step synchron.
        Factor 0.5 slows down the source steps to half speed.
        The same source layer is copied into 2 frames,
        before the advance to the next source layer is done.
        
        The "Step Speed" factor is not relevant for the 
        stepmodes "None" and "FrameNone".

      Selection Handling
        The "Move Path" plug-in can ignore or respect selections (selected Areas)
        in the source image (or source frame(s))
        The Optionmenu Modes are:.
         - "Ignore Selection (in all Source Images)"
              Ignores all selections.
         - "Use Selection (from Initial Source Image)"
              Takes the selection from the initial source image (or frame)
              and applies it to all handled copies.
              This makes all unselected pixels of the moving object
              transparent. You can get smooth edges
              depending on the feather_radius settings in the controlpoints.
         - "Use Selections (from all Source Images)"
              Uses all selections in all source frames.
              The source frames without selections are handled
              as if all pixels were selected.
              This mode is only relevant for the frame based stepmodes, 
             "Frame Loop", "Frame Once", "Frame Loop Reverse",
             "Frame OnceReverse", "Frame PingPong"
               
      
      
      The copies of the source layer(s) were modified by transitions
        with varying parameters.
        Parameters:
       - SourceLayer (depends on Stepmode)
        - Position (X/Y)
        - Size Scaling (Width/Height)
        - Opacity
        - Rotation (angle from -360 to +360 degrees)
        - Selection Feather Radius (in Pixels)
           the feather radius controls how much to smooth the edges of the selections
           (this is only relevant for source selection handling modes other than
           "Ignore Selection")
        - Perspective Transformation (transformation factors for X/Y of the 4 Corner Points)

           Perspective transformation factors are scaling factors
           that are applied to the coordinates of the 4 corners.
           If all 8 Coordinates have the value 1.0 no scaling is done
           and the result is the same as the original.
           Scaling with factor 0 moves the affected (x or y) coordinate to the middle.
           Factor 2.0 applied to Coordinate moves it outwards by half of the
           original width (for X coordinates)
           or half height (for Y coordinates).

                 1/1                       1/1
                  +------------+------------+
                  |            |            |
                  |  x1/y1     |    x2/y2   |
                  | 0.5/0.5    |   0.5/0.5  |
                  |    o...............o    |
                  |   .        |        .   |
                  |  .         |         .  |
                  | .          |0.0       . |
                  +------------+------------+
                 .|            |            |.
                . |            |            | .
               .  |            |            |  .
              .   |            |            |   .
             .    |            |            |    .
            .     |            |            |     .
           .      |            |            |      .
          .       +------------+------------+       .
         .       1/1                       1/1       .
        .                                             .
       o...............................................o
     1.5/1.5                                          1.5/1.5
      x3/y3                                            x4/y4



      The controlpoint parameters were changed from one starting
      controlpoint to the next controlpoint.
      Per default this is a linear change, unless an accelaration characteristic
      is selected.
      Per default the move path has only only 1 controlpoint.
      (So the source layers(s) are copied to all frames of the framerange
       at constant position, size and opacity)
      If you want your source layers to move, grow, rotate or to fade (in or out)
      you have to add one more controlpoints to define a path.

      From Frame: and To Frame:
        The affected range of processed frame images is selected by  From frame - End frame.
        Typically each affected frame receives exactly one copy of the (current)
        source layer adjusted to the current controlpoint parameters.
      
      Layerstack:
        The layerstack defines if the pasted copy appears
        in the foreground (0 == on top) or below other layers that are
        already in the frame.
        
      Target Group: and Delimiter:
        Those entries specify the grouplayer where to insert the rendered object.
        Note that the specified group and subgroups will be created
        automatically in all processed frame images, where they are not already present.
        
        The delimiter entry defines the chracter that separates group from subgroup names,
        per default the slash character "/" acts as name separator.

        Example:
        If your frame image(s) have a layerstack with the following groups:
         
         +----  person     # grouplayer
           +--    head     # grouplayer
                   nose    # normal layer
         +----  animal     # grouplayer
           +--    head     # grouplayer
         Backround         # normal layer     

        and you want to insert a new layer with the name "eye" from source image into the subgroup
        haed of group person, you can use the settings:
          Target Group:  person/head
          Delimiter: /
          Layerstack: 0   (to insert on Top of the group, that is above the "nose" layer) 
          
        The layerstack in all processed frame images will loke like this after MovePath processing is done:

         +----  person     # grouplayer
           +--    head     # grouplayer
                   eye     # normal layer (rendered object inserted by Move Path processing)
                   nose    # normal layer
         +----  animal     # grouplayer
           +--    head     # grouplayer
         Backround         # normal layer     

        
        Note:
        Leave Target Group empty when your Frame Images shall have no layergroups
        and layer insertation shall be done at imagelevel.
        
      Clip To Frame:
      With the checkbox 'Clip To Frame' the the copied layer
      is clipped to the destination frames image width and height.
      
      
      Frame:
      With the frame number entered in the "Frame" entry below the preview,
      you can select the frame number to display in the preview.

      Point:
      This entry below the preview shows number of the current controlpoint.
      Her you can enter a Number to set this number as new current controlpoint.
      
      Instant Apply:
      The Instant Apply checkbox
      does automatic update of the preview when checked.
      The automatic update needs much CPU and IO power
      especially when big images are used as source and/or destination
      or those images have many layers.
      (dont use the instant_apply on slow machines.)


      
      Press the "UpdPreview" button for explicit
      update of the preview.

     Controlpoints:
       The move path is defined by controlpoints.
       Only the current controlpoint is displayed with all
       its values.

       If checkbutton "Show Path" is on, all the controlpoints
       are shown in the preview window, connected with pathlines.
       Further it enables picking controlpoints
       and dragging controlpoint coordinates (X/Y)
       in the preview with the left mousebutton.
       With the right mousebutton you always drag
       the coordinates of the current controlpoint
       (without picking other controlpoints)
       

       There are controlpoint edit buttons to
          "Add Point"
	  "Insert Point"  "Delete Point"

       The Button "Grab Path"
          deletes all controlpoints and replaces them
	  with all anchor points of the vector based gimp path
	  in the invoker image (the image from where the MovePath
	  was started).
	  
	  If you hold down the SHIFT key while you press the 
	  "Grab Path" button, the conversion to controlpoints
	  tries to follow the vector based path along the bezier curve.
	  This is done by creating a controlpoint per handled frame
	  The more controlpoints are used, the closer
	  you get to the original vector based bezier path
	  with the moving object.

       With the Buttons
          "Prev Point"    "Next Point"
	  "First Point"   "Last Point"
          you can step from controlpoint to controlpoint,
	  and make other controlpoint to the current controlpoint.
	  
	  Hold down the SHIFT key when pressing one of those buttons
	  to follow keyframes in the preview.
	  (The target frame with the keyframenumber of the new current controlpoint number
	  is loaded into the Frame: entry and this frame is used for the preview)
	  
	  
       "Reset Point"  "Reset All Points"
          does reset width, height and opacity of the controlpoint to 100%
          , perspective factors to 1.0 (no perspective transformation)
	  and rotation to 0 degree, 
	  but leaves the path (X/Y values) unchanged.


          The "Reset All Points" button has multiple functions
	  controlled by holding down a modifier key:
	  
          - Holding down the shift key copies the setting
	    of point1 into all other points. (except X/Y values)
	  
          - Holding down the ctrl key spreads a mix of
	    the settings of point1 and the last point
	    into the other points inbetween. (except X/Y values)
	
       "Delete All Points"
          removes all controlpoints.
	  
       "Rotate Follow"
          Calculate rotate values for all controlpoints
	  to follow the path.
	  An object moving along a horizontal line 
	  from left to right results in an angle of 0 degree.
	  (or a multiple of 360 degrees if the path
	   builds circular loops)
	  A vertical Move from top to bottom gives 90 degrees.
	  
	  SHIFT: If this button is clicked while the
	  Shift Key is pressed, a fix rotation offset
	  is added to all the calculated rotation values.
	  The rotation offset is taken from the current
	  rotate value of controlpoint 1.
	  
	  If an object moves from right to left
	  the calculated angle is 180 degree and the object
	  appears upside down. 
	  With a startoffset of 180 (or -180)
	  you can compensate this effect.
	  
       "Save Points"
          saves your controlpoints to file in XML representation

       "Load Points"
          loads controlpoints from file
         

      
      Tips:
         - with the UpdPreview Button (or "Instant Apply" checkbox)
           you can blend in the
           selected layer of the source image.
           If you want to adjust position it may be useful to see
           the background.
           Therefore you can make the source image
           transparent (modify the opacity value) or
           put the sourcelayer below the background
           (set the layerstack to higher value)
           Then pres UpdPreview button again.
         
         - Whats wrong if the "UpdPreview" was pressed, 
           but the preview does not show the source object ?
           - maybe the source object is an invisible layer.
             (if the "Force Visibility" checkbox is turned ON
              invisible Layers should become visible).
           - maybe the current opacity setting is 0% (or nearly 0%)
           - maybe the current X and/or Y position are outside
             the image
           - maybe the current scaling factors are 0% (or nearly 0%)
             and the result is only 1x1 pixel or smaller
           - maybe the source object has only fully transparent pixels

         
         - If you let your objects (source layers) rotate,
           perform perspective transformations or
           change their size, set handle mode to 'Center'.
           
           If you use another handle mode you may get unwanted
           moves of your object, caused by resizing.
           
         
         - Speed:
	   If no keyframes are set, and acceleration characteristic value 0 is specified
           the "Move Path" plug-in alternates the settings linear from
           controlpoint to controlpoint, so things move (or happen) in constant speed
           between 2 controlpoints.
           
           If you want to make accelerated moving obcets, you
           can set more controlpoints with growing distances.
           
           Example:
           
           [1] [2]  [3]   [4]    [5]     [6]
            +---+----+-----+------+-------+

           The affected range has 25 frames, and you have set 6 points
           with growing distances in one straight line and without
           specifying keyframes for those points.
           That gives 5 frames (== equal time) for each part of the path,
           but each part has another length. This results in different
           (growing) speeds for each part of the path.
           
      Acceleration characteristic:
      ---------------------------
           
        Since GIMP-GAP-2.7 speed can be controlled with acceleration
        characteristic presets. Those presets are integer values
        where value 1 defines constant speed along a path segment,
        independent to the distance between the controlpoints of the path segment.
        (How to define path segments see chapter Keyframes below)
        positive values result in acceleration, negative values in deceleration.
        

	        
	0 ... implicit speed control, compatible to GAP 2.6.x and older releases
	      (This is the default setting for all acceleration characteristic values)
	      Each line between 2 controlpoints gets an equal time slot (e.g number of frames)
	      The speed between 2 controlpoints is constant, but depends on the length of the line,
	      where short lines result in low speed and long lines result in high speed.
              
        For all other Acceleration characteristic other values than 0
        the line length between controlpoints does not affect
        the speed of the moving object.


        1        ... Constant Speed 
                     object moves through a path segment with constant speed.
                     A path segment includes all path lines between two keyframes
                     (note that first and last controlpoint are considered as keyframes
                     without explicit keyframe value)
                     
                     In this mode the line length between controlpoints does not affect
                     the speed of the moving object.

        positive value ...Acceleration                 
                     object moves through a path segment with increasing speed.
                     higher values result in slower speed at start and higher speed at end
                     of the path segment

        positive value  ...Deceleration
                     object moves through a path segment with decreasing speed.


        Acceleration characteristic values can be specified independent for
        o) Movement     ... Movement of the object
        o) Opacity      ... To control speed of the opacity changes
        o) Size         ... To control speed of size changes (e.g. zooming)
        o) Rotation     ... To control speed of object rotation
        o) Perspective  ... To control speed of object perspective transformations
        o) FeatherRadius... To control speed of selection feather radius changes

        Each of those values can be changed in the Acceleration Tab
        with a spinbutton where you can enter a value.
        A graph next to the spinbutton shows the selected acceleration characteristic curve.
        The acceleration characteristic can also be changed by
        clicking on the graph and dragging vertically with the mouse.
	
	A straight line from left bottom to right top corner of the graph
	is drawn for value 1 that represents constant speed.
        


        Acceleration characteristics are only relevant on the 1st controlpoint, 
        and controlpoints that are marked as KEYFRAME but not on other controlpoints.
        For controlpoints that are not relevant, the spinbutton widgets in the
        acceleration characteristic tab are disabled.

        In case acceleration characteristic values != 0 are used for any other settings than movement
        all controlpoint settings other than positionm (X/Y) of NON-keyframes are ignored.
        (note that first and last controlpoint are
         implicite keyframes and therefore always relevant)
         
        Example:
           have a path with 10 controlpoints, none of them marked as keyframe
           specify rotation 0 for first controlpoint, rotation 360 for the last
           controlpoint and select both Acceleration characteristic for Movement
           and Rotation value 1 (for constant speed)
           
           This settings move the object along the path of 10 points and rotate it
           with constant speed from 0 to 360 degree, regardless what rotation settings
           are define in controlpoints 2,3,4,5,6,7,8,9.

        
        Speed of the moving object can be controlled for each segment of the path,
        where a segment is the distance to the next KEYFRAME. In case there are no
        explicite Keyframes the path has only one segment with full length
        from the first to the last controlpoint.


        When acceleration characteristic other than 0 is used for movement, 
        but not for other transitions (rotation, opacity ...), then the move path
        tool automatically syncronizes frame timing for those other transitions
        with the frametiming of the movement. 
        
        Example:
          Have a path with 5 controlpoints and no explicite keyframe set.
          At the first controlpoint specify acceleration characteristic 12
          for movement to start slow and increase speed of the moving
          object while moving along the path.
          Further let rotation of the object follow the path
          (generate the rotation settings by pressing the "Rotate Follow" button)
          
          In this example the rotation follows the current position of the
          moving object with the same acceleration as the movement.

           
    - Keyframes
        
	Keyframes can be used optional, to fix a controlpoint
	to the given frame number. The first and last controlpoints
	are implicit keyframes, always fixed to start or end
	frame number. (The keyframe entry is set insensitive
	on the first and last controlpoint)
	With the help of keyframes you can control exactly
	when things should happen.
	
	Use a value of 0 in the keyframe entry if you dont want
	to fix a controlpoint to a keyframe.
	
	Keyframes are shown as absolute frame number
	in the "Move Path" dialog window, but they
	are saved as relative values in the
	controlpointfile.
	(if start frame = 5
	 and a keyframe is displayed as 7
	 the keyframe is internally stored as 2 (7 - 5)
	 
	Keyframes are also used to define path segments.
	Where a Path segment includes all following controlpoints
        until the next Keyframe.
        
        Independent acceleration characteristics can be set at
        those controlpoints that are the begin of a path segment.
        (e.g the 1st controlpoint and all keyframes)
        
        The current Segment Number, current segment length (in pixels)
        and minimal / maximal speed (in pixels per tween) are displayed
        below the preview.
        The current Segment is the segment that includes the current
        displayed controlpoint.
        
        Example:
          You have 500 frames and want to render an object
          that stands still at coordinate 320/200 in the 1st 50 frames,
          than accelerates until frame 150, moves with constant speed
          until frame 400, decelerates until frame 450 and stays still
          at coordinate 470/150 until the end frame 500.
          
          Tip: 
          To avoid unwanted speed jumps in this multi segmented
          example, the controlpoints should be set in a way 
          that max speed value of segment B is nearly equal
          to the max speed value of Segment C and segment D.
          Note that changes of control point coordinates affect the
          length of the path segment, acceleration characteristic,
          and number of involved frames (or tweens) also have
          influence on the speed of the object within a segment.
          
        
        #Segment  A  (standstill in Segment Number 0)
        [ 0]  x:320 y:200

        #Segment B  (increasing speed due to acceleration value 20 for Movement)
        [ 1]  x:320 y:200  keyframe:50    acceleration Movement: 20
        [ 2]  x:330 y:210
        [ 3]  x:350 y:200
        [ 4]  x:360 y:190

        #Segment C  (move with constant speed due to acceleration value 1 for Movement)
        [ 5]  x:362 y:170  keyframe:150   acceleration Movement: 1
	[ 6]  ...
	[ 7]  ...
	[ 8]  ...
	[ 9]  ...
	[10]  ...       
	
        #Segment D  (decreasing speed due to acceleration value -15 for Movement)
        [11]  x:500 y:150  keyframe:400   acceleration Movement: -15
        [12]  x:490 y:160
        [13]  x:475 y:155
        [14]  x:475 y:155

        #Segment E  (standstill)
        [15]  x:470 y:150  keyframe:450
        [16]  x:470 y:150



	 
	 
     - Checking Controlpoints
        - The check is done at "OK", and "Anim Preview"
	  button,
	  If errors are detected, they are shown
	  in a pop-up window and the action is not performed.
        - The number of controlpoints is now checked
	  against the number of affected frames.
	  (You can't have more controlpoints than frames)
	- If keyframes are used, they must be in
	  (ascending or descending) sequence
	 
          
     - AnimPreview
        With this button you can generate an animated preview
	to get an idea how the inserted moving object
	will look like. The animated preview is generated
	as multilayer image and the Filter/Animation/Playback
	plug-in is started on that multilayer image.
	
	The button opens a dialog window, where you can
	enter options for the animated preview.
	
	- Object on empty frames
	    renders quick on empty frames (filled with background color)
	    (scale down speeds up rendering time)
	- Object on one frame
	    renders quick on one frame (preview frame)
	    (scale down speeds up rendering time)
	- Exact Object on frames
	    renders slow, but exactly on the selected framerange.
	    (scale down increases rendering time)

        - Scale Preview
	    Optional you can scale down the animated preview
	    size (100% downto 5%)
	    
	- Framerate
	    The framerate is used in the generated 
	    multilayer image only.
	    
	- Copy to Video Buffer   
	  Optional you can copy the preview frames
	  to the video buffer
	  (can be pasted in the GIMP-GAP VCR Navigator)
    
    - Force visibility
         If this checkbutton is set, all source layerobjects
	 are set visible when they are copied into frames.


    Tab "Advanced settings"
    -----------------------------
    
    - Bluebox
         With the bluebox check_button you can apply the bluebox filter effect
         on the moving object, that makes the keycolor transparent.

    - The Keycolor button
         Opens a dialog window where you can set all the parameters
         of the bluebox filter.
         If clicked with the right mouse button you can grab the keycolor
         from the current FG/BG color (in the GIMP main window)
         
    
    - Tracelayer
         a trace layer shows all positions of the moving object
	 from begin until the position of the previous frame.
	 Positions in virtual frames (tweens) are also included
	 in the trace layer.
	 If descending Opacity is used, the trace is fading out
	 at the older (previous) Positions of the moving object.
    
    -Tweensteps
        This feature is for rendering fast moving Objects.

        The "MovePath" plug-in can calculate the moving object for virtual frames (tweens)
        between real frames. You can control this by setting tween_steps
        to a value greater than 0.
        In that case the "MovePath" plug-in creates an additional layer
        (the "Tweenlayer") and inserts that tween layer below the
        stackposition of the current moving object in the next real frame.
        The tween layer shows the moving object at the positions of
        all virtual frames between two real frames.
	
        Example: The selected frame range is 10 frames and
        the tweensteps value is 2. In this case 28 steps
        are processed internal. 10 real frames + 18 virtual frames
        (2 virtual between each real frame)
        Use descending opacity to fade out tweens.
        The tween nearest to the real frame is drawn with the initial
	opacity value, the other tweens are reduced more and more
	if descending opacity is less than 100%.
	With tweens and opacity settings you can produce motion-blur effects
	for fast moving objects.

        If both tween processing and trace layer are active, the
	"Tweenlayer" is added, but set invisible.
	This is done because the trace layer contains already all the tween steps.
	A visible tween layer would produce unwanted increase
	of the total opacity of the moving object in the composite view.

    Tab Merge Settings
    -----------------------------
      The MovePath Merge Postprocessor is configured via the Option Menus in 
      the Merge Settings Tab of the Move Path Dialog Window.
    
      This tab has 3 Option Menus in the upper row and decribes how optional postprocessing
      shall be performed on the 3 Layertypes that can be created by the MovePath processing
      in each handled frame image.
      Those 3 Layertypes are:
      1) The Renderd Object is the transformed Copy of the selected Source Object, 
      2) Tween Layer (optional creation depends on "Advanced settings" see above)
      3) Trace Layer (optional creation depends on "Advanced settings" see above)
      
      OM1: Option Menu for Renderd Object
        (k) Keep Rendered Object as Layer
              This is the default setting (that triggers no postprocessing), 
              where the Moving Object is inserted
              into the processed frames as a new Layer
        (m) Merge Down Rendered Object
              Use this to merge the rendered Object to the Merge target.
        (d) Delete Rendered Object
              Use this to delete the rendered Object
              (For the rare cases when just the Tween or Trace Layer shall be rendered
              
        
      OM2: Option Menu for Tween Layer (is ignored when no Tween Layer is present)
        (k) Keep Tween Layer
        (m) Merge Down Tween Layer
        (d) Delete Tween Layer
        
      OM3: Option Menu for Trace Layer (is ignored when no Trace Layer is present)
        (k) Keep Trace Layer
        (m) Merge Down Trace Layer
        (m) Delete Tween Trace

      The 2nd row defines the Merge Target with one Option Menu
      The Merge target is ignored when none on the 3 Layertypes was selected
      for Merge Down, 
      but is used as Common Target for each of the Layertypes when they
      were rendered by Move Path processing and the "Merge Target" option is selcted.
      
      OM4: Option Menu to select the Merge Target 
        (a) New Layer
             ?? creates a new transparent Layer at frame image size
             (below the inserted Layers rendered by MovePath processing)
             and merge
        (b) Merge To Layer Below
        (c) Merge To New Black Mask At Layer Below
        (d) Merge To New White Mask At Layer Below
        (e) Merge To existing Mask At Layer Below
        
        
    The MovePath Merge Postprocessor handles merging 
    and removal of layers in the processed frame images.
      
    The (optional) merge affects layers that were created / rendered by MovePath render processing
    in the following Stackposition order.
         MovingObjectLayer  renderedObjectLayerId  
         Tweenlayer         tweenLayerId   (optionally present when tween layer feature is active)
         Tracelayer         traceLayerId   (optionally present when trace layer feature is active)
         a layer below      existingLayerBelowId (may not be present when inserting on bottom of layerstack or group)
 
    in case any merge action is required (in menus OM1->m, OM2->m, OM3->m)
    a working layer is created at frame image size.
    The work layer will be fully transparent (in case the merge target is NOT a Lyermask)
    or may be BLACK opaque, WHITE opaque and optionally copied from an already existing layer mask
    (in case the merge target is a layermask -- when OM4->e was selected in the dialog)
    
          /* now layerstack shall look like this:
           *   renderedObjectLayerId (foreground)
           *   [ tweenLayerId ]      (optional) 
           *   [ traceLayerId ]      (optional)
           *   workLayerId

    
    
    The renderedObject, Tween and Trace layer(s) will be merged down to the newly created worklayer.
    and the merged working layer is then either:
       o) copied into the layermask (and removed)  ... for mergeTarget OM4->c, OM4->d, OM4->e types GAP_MPP_TARGET_LOWER_LAYERS_MASK_*
       o) mereged down to the existing Layer Below ... for mergeTarget OM4->b  type GAP_MPP_TARGET_LOWER_LAYER
       o) kept as final render result              ... for mergeTarget OM4->a  type GAP_MPP_TARGET_NEW_LAYER        
        


   Note that Merging with the worklayer is done in Gimp Mergemode GIMP_EXPAND_AS_NECESSARY.
   Therfore the Merged result has either has at least fraqme image size, or may be bigger in case
   the RenderedObject was bigger or had a position where some parts ot it are outside the frame image boundaries.
   Note that this can not occure when 'Clip To Frame' checkbox is selected.
   
   Tip: 
   To force all rendered Objectes to exact frame image size
   - set the 'Clip To Frame' checkbox to selected state,
   - Use Merge Settings
       OM1->m  Merge Down Rendered Object
       OM4->a  New Layer as merge target.
       
       
   
