This project has moved and is read-only. For the latest updates, please go here.

API Overview in C#

This page provides a basic overview of loading and running 3rd party Adobe® Photoshop®-compatible filters in C#.

Contents

Searching a directory for filters

The EnumerateFilters function searches a directory (and optionally any sub directories) for filters.
The directories may contain both filters and shortcuts to filters in other locations outside of the directories being searched.

var filters = new Dictionary<stringToolStripMenuItem>(StringComparer.Ordinal);
List<ToolStripItem> aboutList = new List<ToolStripItem>();
SearchOption option = SearchOption.AllDirectories; foreach (PluginData plug in PSFilterHost.EnumerateFilters(@"C:\Plug-Ins", option)) {
// The **Hidden** category is used for filters // that are not directly invoked by the user. if (plug.Category.Equals("**Hidden**"StringComparison.Ordinal)) { continue; } ToolStripMenuItem child = new ToolStripMenuItem(plug.Title, null, RunFilter_Click); child.Name = plug.Title; child.Tag = plug; ToolStripMenuItem aboutItem = new ToolStripMenuItem(plug.Title, null, ShowAboutBox); aboutItem.Tag = plug; if (filterList.ContainsKey(plug.Category)) { ToolStripMenuItem parent = filters[plug.Category]; if (!parent.DropDownItems.ContainsKey(plug.Title)) { parent.DropDownItems.Add(child); if (plug.HasAboutBox) { aboutList.Add(aboutItem);  } } } else { ToolStripMenuItem parent = new ToolStripMenuItem(plug.Category, null, child); filters.Add(plug.Category, parent); if (plug.HasAboutBox) { aboutList.Add(aboutItem);  } } }

Optional callbacks, methods, events and properties

Callbacks

The abort callback allows the host to signal the filter to cancel any rendering currently in progress. The filter will poll this callback during long operations and stop processing if it returns true.

private bool AbortFilterCallback()
{
    return escapePressed;
}

The color picker callback allows the host to show it's own color picker in place of the Windows color dialog when a filter requests that the user choose a color. The filter may specify a prompt for the user (e.g. Please choose a color: ), if the filter does not set a prompt this will be an empty string. The red, green and blue parameters specify the initial color that the filter wants selected in the host's color dialog.

private ColorPickerResult PickColorCallback(string prompt, byte red, byte green, byte blue)
{
    ColorPickerResult color = null;
 
    using (ColorPickerForm dialog = new ColorPickerForm(prompt))
    {
        dialog.SetDefaultColor(red, green, blue);
 
        if (dialog.ShowDialog() == System.Windows.Forms.DialogResult.OK)
        {
            color = new ColorPickerResult(dialog.UserPrimaryColor);
        }
 
    }
 
    return color;
}

Methods

The SetColorProfiles method allows the host to specify the International Color Consortium (ICC) color profiles of the document and monitor which are used to apply color correction to the preview image displayed by the filter.

this.hostColorProfiles = new HostColorManagement(documentProfile, this.monitorProfilePath);

Events

The UpdateProgress event allows the filter to inform the host of it's rendering progress.

private void UpdateFilterProgress(object sender, FilterProgressEventArgs e)
{
    this.toolStripProgressBar1.Value = e.Progress;
}

Properties

The HostInfo property allows the filter to retrieve information about the current document from the host, such as the title and preferred ruler measurement unit.

this.hostInfo = new HostInformation();
this.hostInfo.Title = this.imageFileName;
this.hostInfo.RulerUnit = HostRulerUnit.Inches;

The PseudoResources property allows the filter to store data which will persist for the current session, this can be used for communication between filters.

PseudoResourceCollection pseudoResources = null;

Executing a filter

The filter execution steps consist of:

  1. Calling one of the PSFilterHost constructor overloads.
  2. Optionally set the abort callback, color picker callback, progress event handler and other properties.
  3. Set the FilterParameters property to restore the last used settings (if any).
  4. Calling one of the RunFilter overloads with the PluginData of the filter you want to execute.
  5. Update the output image and save the FilterParameters and other properties that the filter may have modified.

When the FilterParameters have been set to execute a filter with settings from a previous session the RunFilter(PluginData) overload will not show the user interface. The RunFilter(PluginData, Boolean) overload allows the host to display the filters user interface initialized to the previous settings. The host should display the filters user interface unless it was invoked through a 'Repeat Filter' command.


Note: The dimensions of the image to be filtered must be less than or equal to 32000 pixels in width and/or height or an ImageSizeTooLargeException will be thrown (this is due to the Adobe® Photoshop® API using signed 16-bit integers for the image dimensions).

using (PSFilterHost host = new PSFilterHost(sourceImage, foreColor, backColor, selection, owner))
{
    host.SetAbortCallback(new AbortFunc(AbortFilterCallback));
    host.SetPickColorCallback(new PickColor(PickColorCallback));
    host.UpdateProgress += new EventHandler(UpdateProgress);

    if (this.filterParameters.ContainsKey(pluginData))
    {
        host.FilterParameters = this.filterParameters[pluginData];
    }

    if ((this.pseudoResources != null) && this.pseudoResources.Count > 0)
    {
        host.PseudoResources = this.pseudoResources;
    }

    host.HostInfo = this.hostInfo;
    if  (this.hostColorProfiles != null)
    {
        host.SetColorProfiles(this.hostColorProfiles);
    }

    if (host.RunFilter(pluginData, showUI))
    {
        this.destinationImage = host.Dest;

        if (showUI)
        {
            // Add or update the  last used parameters of the filter. 
            if (this.filterParameters.ContainsKey(pluginData))
            {
                this.filterParameters[pluginData] = host.FilterParameters;
            }
            else
            {
                this.filterParameters.Add(pluginData, host.FilterParameters);
            }
 
            // Save the other information that may have been changed by the filter.
            this.pseudoResources = host.PseudoResources;
            this.hostInfo = host.HostInfo;
        }
    }
}

Displaying the filter about box

The ShowAboutDialog function displays the filter's about box (if it has one).

PSFilterHost.ShowAboutDialog(pluginData, parentWindowHandle);

Last edited Aug 28, 2016 at 1:18 AM by 0xC0000054, version 23