home *** CD-ROM | disk | FTP | other *** search
/ PC Pro 2002 April / pcpro0402.iso / essentials / graphics / Gimp / gimp-src-20001226.exe / src / gimp / plug-ins / gap / README_developers < prev    next >
Encoding:
Text File  |  1999-03-17  |  8.6 KB  |  260 lines
  1. This README_developers file should be read by Plug-In authors:
  2.  
  3. How to make a GIMP Plug-In an "Animated" one:
  4. ---------------------------------------------
  5.  
  6. First of all:
  7.  
  8.    the plugin must be able to operate on a single Drawable,
  9.                               ----------------------------
  10.    further it must be able to run with last_values and in interactive mode.
  11.                               --------------------        -----------                                
  12.    
  13.    For the Animated Plugin Call we need an Iterator Procedure.
  14.    This Procedure is named like the Plugin with the extension "_Iterator".
  15.    The Iterator Procedure has to know the Plugin's internal datastructure
  16.    and has to modify Its "LastValues" step by step at each call.
  17.    
  18.    The GAP-PDB-Browser <Image>/Filters/Animation/Filter All Layers
  19.    checks for the existance of Iterator Procedures in the PDB
  20.      1.)  <plugin_name>_Iterator
  21.      2.)  <plugin_name>_iter_ALT
  22.      
  23.    If one of the iterator procedures was found in the PDB, the
  24.    "Apply Varying" Button is set sensitive to allow animated calls
  25.    for the selected procedure.
  26.    
  27.    
  28.    If you have gap prerelease 0.93.00 or later you can generate 
  29.    the "plug_in_XXXX_Iterator"
  30.    for a Plugin as seperated Sourcefile, ready to compile.
  31.    (The Plugin must be found in the PDB at generation time)
  32.    
  33.    # this example uses the Plugin whirlpinch
  34.    
  35.    1.a  # for bourne and ksh users:
  36.    
  37.         GAP_DEBUG=y
  38.         export GAP_DEBUG
  39.         
  40.    1.b # for csh users
  41.        setenv GAP_DEBUG y
  42.     
  43.    2.  # change to the directory, where you like to generate the sourcecode
  44.        cd /usr/local/gimp-0.99.17/plug-ins/whirlpinch
  45.    
  46.    3.  # start the Gimp
  47.        gimp
  48.  
  49.    4.  # open or create any image
  50.        File->New
  51.    
  52.    5.  # call the GAP Plugin for Animated Filter apply
  53.        # from within the image
  54.        Filters->Animation->Filter all Layers
  55.        
  56.        # if you have set GAP_DEBUG as shown above,
  57.        # the Window should contain the Button "Gen Code by name"
  58.        
  59.        # Type the name of your Plugin into the Search Inputfield
  60.        # (Click "Search by Name" Button, to check if the Plugin
  61.        # is available in the PDB)
  62.        
  63.        # Then click "Gen Code by Name" Button and then "Cancel" Button.
  64.        
  65.        # This will generate 4 files in the current directory:
  66.            gen_filter_iter_forward.c
  67.            gen_filter_iter_tab.c
  68.            plug_in_whirl_pinch_iter_ALT.inc
  69.            plug_in_whirl_pinch_iter.c
  70.            
  71.        # You can quit the gimp and delete the 3 files named "gen_filter_iter_*"
  72.        
  73.   6. # compile and link the generated Source,  plug_in_whirl_pinch_iter.c
  74.      # and install the linked executeable
  75.      # in global or private plug-in directory
  76.      
  77.      gimptool --install  plug_in_whirl_pinch_iter.c
  78.      
  79.      # (if you dont have gimptool, you can use a copy of the original Plugin's Makefile
  80.      # and change the Plugins <name> by <name_iter> to do that job.)
  81.      
  82.  
  83.   7. # start the gimp again,
  84.      # and open or create an Image that has at least 3 Layers.
  85.      # Test the "Animated Filter apply"
  86.   
  87.      Filters->Animation->Filter all Layers
  88.      
  89.      # Use the "Apply Varying" Button, 
  90.      # it should be sensitive now (if all went well so far).
  91.   
  92.   8. # In case of error:
  93.      # If you get an Error Message (in the shell, where you started the gimp)
  94.      # that looks like:
  95.      
  96.         ERROR: xxxx_Iterator stored Data missmatch in size N != M
  97.     
  98.      # you have to change the generated code manually.
  99.      # (check for calls to "gimp_set_data" or "gimp_get_data" that are using
  100.      # the plugins name as key argument within the plugin's sourcecode.
  101.      # The passed datastructure has to match exactly in size with the generated one
  102.      # for the example above the generated structure is:
  103.      # plug_in_whirl_pinch_iter.c: 
  104.          typedef struct t_plug_in_whirl_pinch_Vals 
  105.          {
  106.            gdouble   whirl;
  107.            gdouble   pinch;
  108.            gdouble   radius;
  109.          } t_plug_in_whirl_pinch_Vals;        
  110.  
  111.  
  112. If you are the Author of a Plugin you may decide to include the _Iterator
  113. within the original Sources of your Plugin. In that case you have to check
  114. the name argument in the run procedure.
  115.  
  116.  
  117.  
  118.  
  119. Example Code:
  120.  
  121. query()
  122. {
  123.   static GParamDef args_plugin[] =
  124.   {
  125.     {PARAM_INT32, "run_mode", "non-interactive"},
  126.     {PARAM_IMAGE, "image", "the image"},
  127.     {PARAM_DRAWABLE, "drawable", "the drawable"},
  128.     {PARAM_INT32, "value", "my_parameter value"},
  129.   };
  130.   static int nargs_plugin = sizeof(args_plugin) / sizeof(args_plugin[0]);
  131.  
  132.   static GParamDef args_iter[] =
  133.   {
  134.     {PARAM_INT32, "run_mode", "non-interactive"},
  135.     {PARAM_INT32, "total_steps", "total number of steps (# of layers-1 to apply the related plug-in)"},
  136.     {PARAM_FLOAT, "current_step", "current (for linear iterations this is the layerstack position, otherwise some value inbetween)"},
  137.     {PARAM_INT32, "len_struct", "length of stored data structure with id is equal to the plug_in  proc_name"},
  138.   };
  139.   static int nargs_iter = sizeof(args_iter) / sizeof(args_iter[0]);
  140.  
  141.   static GParamDef *return_vals = NULL;
  142.   static int nreturn_vals = 0;
  143.  
  144.   gimp_install_procedure("plug_in_XXXX,
  145.              "plug_in_XXXX can do ....",
  146.              "",
  147.              "Authors Name",
  148.              "Copyright",
  149.              "Date",
  150.              "<Image>/Filters/Effects/XXXX",
  151.                  "RGB*, INDEXED*, GRAY*",
  152.                          PROC_PLUG_IN,
  153.              nargs_plugin, nreturn_vals,
  154.              args_plugin, return_vals);
  155.  
  156.  
  157.   gimp_install_procedure("plug_in_XXXX_Iterator,
  158.              "This extension calculates the modified values for one iterationstep for the call of plug_in_XXXX",
  159.              "",
  160.              "Authors Name",
  161.              "Copyright",
  162.              "Date",
  163.              NULL,    /* do not appear in menus */
  164.              NULL,
  165.              PROC_EXTENSION,
  166.              nargs_iter, nreturn_vals,
  167.              args_iter, return_vals);
  168. }
  169.  
  170.  
  171.  
  172.  
  173. static void p_delta_long(long *val, long val_from, long val_to, gint32 total_steps, gdouble current_step)
  174. {
  175.     double     delta;
  176.  
  177.     if(total_steps < 1) return;
  178.  
  179.     delta = ((double)(val_to - val_from) / (double)total_steps) * ((double)total_steps - current_step);
  180.     *val  = val_from + delta; 
  181.  
  182. }
  183.  
  184.  
  185.  
  186. static void
  187. run (char    *name,
  188.      int      n_params,
  189.      GParam  *param,
  190.      int     *nreturn_vals,
  191.      GParam **return_vals)
  192. {
  193.   static GParam values[1];
  194.   GStatusType status = STATUS_SUCCESS;
  195.   GRunModeType run_mode;
  196.   gint32  len_struct;
  197.   gint32  total_steps;
  198.   gdouble current_step;
  199.  
  200.   long    pval;                  /* plug_in_XXXX has one parameter of type long */
  201.   long   *pval_from, *pval_to;   /* values for 1.st and last layer
  202.                                   * when they were processed by "plug_in_gap_layers_run_animfilter"
  203.                                   */
  204.  
  205.   *nreturn_vals = 1;
  206.   *return_vals = values;
  207.    values[0].type = PARAM_STATUS;
  208.  
  209.   
  210.   run_mode = param[0].data.d_int32;
  211.   
  212.   if (strcmp (name, "plug_in_XXXX") == 0)
  213.   {
  214.      ....  /* start the plugin itself */
  215.   }
  216.   else  if (strcmp (name, "plug_in_XXXX_Iterator") == 0)
  217.   {
  218.       /* Iterator procedure is usually called from
  219.        * "plug_in_gap_layers_run_animfilter"
  220.        * (always run noninteractive)
  221.        */
  222.       if ((run_mode == RUN_NONINTERACTIVE) && (n_params == 4))
  223.       {
  224.         total_steps  =  param[1].data.d_int32;
  225.         current_step =  param[2].data.d_float;
  226.         len_struct   =  param[3].data.d_int32;
  227.  
  228.         if(len_struct == sizeof(pval))
  229.         {
  230.           /* get _FROM and _TO data, 
  231.            * This data was stored by plug_in_gap_layers_run_animfilter
  232.            */
  233.         
  234.           gimp_get_data("plug_in_XXXX_ITER_FROM", pval_from); 
  235.           gimp_get_data("plug_in_XXXX_ITER_TO",   pval_to); 
  236.  
  237.           p_delta_long(&pval, *pval_from, *pval_to, total_steps, current_step);
  238.  
  239.           gimp_set_data("plug_in_XXXX", &pval, sizeof(pval));
  240.         }
  241.         else status = STATUS_CALLING_ERROR;
  242.       }
  243.       else status = STATUS_CALLING_ERROR;
  244.   }
  245.  
  246.    values[0].type = PARAM_STATUS;
  247.    values[0].type = PARAM_STATUS;
  248.  
  249. }
  250.  
  251.  
  252. Important for Plugin_Authors:
  253.    I have made Iterator Procedures for more than 50 existing Procedures.
  254.    (see gap_filter_iterators.c and subdirectories iter_ALT/*/*.inc)
  255.    If your Plugin is found in gap_filter_iterators.c, and You make updates 
  256.    to your Plugin's interface, you should write (or generate) your own _Iterator Procedure,
  257.    to keep its Animated capabilities intact.
  258.    (You don't need to change gap sources to do that, because the Iterator
  259.    named "plug_in_XXXX_Iterator" is used rather than "plug_in_XXXX_Iterator_ALT" )
  260.