package ij.plugin.filter;
import ij.*;
import ij.process.*;

/** ImageJ plugins that process an image may implement this interface.
 *  In addition to the features of PlugInFilter, it is better suited
 *  for filters that have a dialog asking for the options or filter
 *  parameters. It also offers support for preview, for a smooth
 *  progress bar when processing stacks and for calling back
 *  the PlugInFilterRunner (needed, e.g., to get the slice number
 *  when processing a stack in parallel threads).
 *

 *  The sequence of calls to an ExtendedPlugInFilter is the following:
 *

 *  - setup(arg, imp):  The filter should return its flags.  

 *  - showDialog(imp, command, pfr): The filter should display
 *         the dialog asking for parameters (if any) and do all operations
 *         needed to prepare for processing the individual image(s) (E.g.,
 *         slices of a stack). For preview, a separate thread may call
 *         setNPasses(nPasses) and run(ip) while
 *         the dialog is displayed. The filter should return its flags.   

 *  - setNPasses(nPasses): Informs the filter of the number
 *         of calls of run(ip) that will follow.             

 *  - run(ip): Processing of the image(s). With the
 *         CONVERT_TO_FLOAT flag, this method will be called for
 *         each color channel of an RGB image. With DOES_STACKS,
 *         it will be called for each slice of a stack.                   

 *  - setup("final", imp): called only if flag
 *         FINAL_PROCESSING has been specified.
 *

 * Flag DONE stops this sequence of calls.
 */
public interface ExtendedPlugInFilter extends PlugInFilter {

    /**
     * This method is called after setup(arg, imp) unless the
     * DONE flag has been set.
     * @param imp The active image already passed in the
     * setup(arg, imp) call. It will be null, however, if
     * the NO_IMAGE_REQUIRED flag has been set.
     * @param command The command that has led to the invocation of
     * the plugin-filter. Useful as a title for the dialog.
     * @param pfr The PlugInFilterRunner calling this plugin-filter.
     * It can be passed to a GenericDialog by addPreviewCheckbox
     * to enable preview by calling the run(ip) method of this
     * plugin-filter. pfr can be also used later for calling back
     * the PlugInFilterRunner, e.g., to obtain the slice number
     * currently processed by run(ip).
     * @return  The method should return a combination (bitwise OR)
     * of the flags specified in interfaces PlugInFilter and
     * ExtendedPlugInFilter.
     */
    public int showDialog(ImagePlus imp, String command, PlugInFilterRunner pfr);

    /**
     * This method is called by ImageJ to inform the plugin-filter
     * about the passes to its run method. During preview, the number of
     * passes is one (or 3 for RGB images, if CONVERT_TO_FLOAT
     * has been specified). When processing a stack, it is the number
     * of slices to be processed (minus one, if one slice has been
     * processed for preview before), and again, 3 times that number
     * for RGB images processed with CONVERT_TO_FLOAT.
     */
    public void setNPasses(int nPasses);

    /** Set this flag if the last preview image may be kept as a result.
        For stacks, this flag can lead to out-of-sequence processing of the
        slices, irrespective of the PARALLELIZE_STACKS flag.
     */
    public final int KEEP_PREVIEW = 0x1000000;

	
}