怎样编写一个Photoshop滤镜（3） Scripting Plugins

            在第一篇文章中我们建立了一个没有UI的基本滤镜框架，并且引入PIPL资源使之能被PS加载到菜单。在第二篇文章中我们又引入了滤镜参数和相应的对话框资源，并且讲解了对话框在滤镜调用流程中的显示时机。这一篇文章我们将使滤镜支持动作记录和回放，也就是通过添加“术语资源”，使我们的滤镜参数被PS的脚本系统所获知（scripting-aware），并能够记录和回放。

            从Photoshop 4.0开始引入了一个新的面板以及相应的命令和回调函数：动作面板（浮动窗口），以及Descriptor 回调函数集。动作面板是Photoshop脚本系统用于和用户交互的接口，也是其核心所在。Photoshop 5.0扩展了动作结构，使自动化插件能够支持可描述的Photoshop命令。（《Photoshop API Guide》第11章）

            关于PS的 Scripting System，其来源是 PS 对苹果系统的事件和脚本机制的继承和支持，PS 的开发同时针对两种操作系统平台。这里我们介绍如何使我们的滤镜被PS脚本系统接纳。

            首先我们需要在 r文件中增加术语资源（terminology resource）。因此首先在 pipl 资源中增加一个 HasTerminology 结构，其定义如下：

//这个属性指明滤镜是否提供了 'aete'资源。
typedef struct HasTerminology
{
int32 classID; // classID from 'aete'
int32 eventID; // eventID from 'aete' or NULL if none
int16 aeteResNum; // number of 'aete' resource
CString uniqueID; // unique ID string (UUID or your own ™/©). If present,
ignores AppleScript and keeps local to Photoshop.
} HasTerminology;

            这个结构将被增加到 r文件的 pipl资源内。下面我们在pipl资源后面添加了 aete 资源。

            在此前我们在一个通用的头文件中添加一些aete资源需要的定义：

//定义 Scripting Keys
#define KEY_FILLCOLOR        'fiCo'
#define KEY_OPACITY            'opcA'

#define plugInSuiteID        'filR'
#define plugInClassID        'filR'
#define    plugInEventID        'filR'
#define    plugInUniqueID        "18EC4E8F-DB34-4aff-AF99-77C8013BD74F"
#define plugInAETEComment    "FillRed example filter By hoodlum1980"
#define vendorName            "hoodlum1980"

            上面我们把我们的滤镜，滤镜的参数都定义为了键，关于键定义，需要符合以下原则：

            （a）它必须由4个字符组成。不够4个字符可以结尾用空格补足。

            （b）用户定义的键名应该以小写字母开头，同时至少含有一个大写字母。（因为全大写，全小写键名属于Apple定义）。

            滤镜的唯一标识符采用VC工具生成的GUID即可。

            

            然后我们对r文件增加aete 资源，aete 资源模板如下：

resource 'aete' (0)
{ // aete version and language specifiers
{ /* suite descriptor */
{ /* filter/selection/color picker descriptor */
{ /* any parameters */
/ * additional parameters */
}
},
{ /* import/export/format descriptors */
{ /* properties. First property defines inheritance. */
/* any properties */
},
{ /* elements. Not supported for plug-ins. */
},
/* class descriptions for other classes used as parameters or properties */
},
{ /* comparison ops. Not currently supported. */
},
{ /* any enumerations */
{
/* additional values for enumeration */
},
/* any additional enumerations */
/* variant types are a special enumeration: */
{
/* additional types for variant */
},
/* any additional variants */
/* class and reference types are a special enumeration: */
{
},
/* any additional class or reference types */
}
}
}

            请注意的是这是一个针对PS插件的aete资源模板，也就是说它不仅仅针对滤镜，也包括其他种类的PS插件。关于其具体含义这里我们不做详细讨论，可以参考相关PS SDK文档。

            【注意】即使有的节不需要，也必须提供一个空的花括号占位，而不能有缺失。 

            下面我们给出添加了aete资源后的 FillRed.r 文件，内容如下：

// ADOBE SYSTEMS INCORPORATED
// Copyright  1993 - 2002 Adobe Systems Incorporated
// All Rights Reserved
//
// NOTICE:  Adobe permits you to use, modify, and distribute this 
// file in accordance with the terms of the Adobe license agreement
// accompanying it.  If you have received this file from a source
// other than Adobe, then your use, modification, or distribution
// of it requires the prior written permission of Adobe.
//-------------------------------------------------------------------------------
#define plugInName            "FillRed Filter"
#define    plugInCopyrightYear "2009"
#define plugInDescription \
    "FillRed Filter.\n\t - http:\\www.cnblogs.com\hoodlum1980"

#include "E:\Codes\Adobe Photoshop CS2 SDK\samplecode\common\includes\PIDefines.h"

#ifdef __PIMac__
    #include "Types.r"
    #include "SysTypes.r"
    #include "PIGeneral.r"
    #include "PIUtilities.r"
    #include "DialogUtilities.r"
    #include "CommonDefine.h"        /* 包含了术语定义 */
#elif defined(__PIWin__)
    #define Rez
    #include "PIGeneral.h"
    #include "E:\Codes\Adobe Photoshop CS2 SDK\samplecode\common\resources\PIUtilities.r"
    #include "E:\Codes\Adobe Photoshop CS2 SDK\samplecode\common\resources\WinDialogUtils.r"
    #include "CommonDefine.h"        /* 包含了术语定义 */
#endif

#include "PITerminology.h"
#include "PIActions.h"                /* 包含对 NO_REPLY 的定义 */

resource 'PiPL' ( 16000, "FillRed", purgeable )
{
    {
        Kind { Filter },
        Name { plugInName },
        Category { "Demo By hoodlum1980" },
        Version { (latestFilterVersion << 16) | latestFilterSubVersion },
        #ifdef __PIWin__
            CodeWin32X86 { "PluginMain" },
        #else
            CodeMachOPowerPC { 0, 0, "PluginMain" },
        #endif

        SupportedModes
        {
            noBitmap, doesSupportGrayScale,
            noIndexedColor, doesSupportRGBColor,
            doesSupportCMYKColor, doesSupportHSLColor,
            doesSupportHSBColor, doesSupportMultichannel,
            doesSupportDuotone, doesSupportLABColor
        },
        
        HasTerminology
        {
            plugInClassID,
            plugInEventID,
            16000,                /* int16 aeteResNum;  number of 'aete' resource */
            plugInUniqueID
        },
            
        EnableInfo
        {
            "in (PSHOP_ImageMode, RGBMode,"
            "CMYKMode, HSLMode, HSBMode, "
            "DuotoneMode, LabMode)"
        },

        PlugInMaxSize { 2000000, 2000000 },

        FilterCaseInfo {
            {    /* array: 7 elements */
                /* Flat data, no selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Flat data with selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Floating selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Editable transparency, no selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Editable transparency, with selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Preserved transparency, no selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination,
                /* Preserved transparency, with selection */
                inStraightData,
                outStraightData,
                doNotWriteOutsideSelection,
                doesNotFilterLayerMasks,
                doesNotWorkWithBlankData,
                copySourceToDestination
            }
        }
    }
};


resource 'aete' (16000, "FillRed dictionary", purgeable)
{
    1, 0, english, roman,                                    /* aete version and language specifiers */
    {
        vendorName,                                            /* vendor suite name */
        "FillRed Demo By hoodlum1980",                        /* optional description */
        plugInSuiteID,                                        /* suite ID */
        1,                                                    /* suite code, must be 1 */
        1,                                                    /* suite level, must be 1 */
        {                                                    /* structure for filters */
            plugInName,                                        /* unique filter name */
            plugInAETEComment,                                /* optional description */
            plugInClassID,                                    /* class ID, must be unique or Suite ID */
            plugInEventID,                                    /* event ID, must be unique to class ID */
            
            NO_REPLY,                                        /* never a reply */
            IMAGE_DIRECT_PARAMETER,                            /* direct parameter, used by Photoshop */
            {                                                /* parameters here, if any */
                "FillColor",                                /* parameter name */
                KEY_FILLCOLOR,                                /* parameter key ID */
                typeInteger,                                /* parameter type ID */
                "Fill color in RGB",                        /* optional description */
                flagsSingleParameter,                        /* parameter flags */
                
                "Opacity",                                    /* optional parameter */
                KEY_OPACITY,                                /* key ID */
                typeInteger,                                /* type */
                "opacity in RGB",                            /* optional desc */
                flagsSingleParameter                        /* parameter flags */
            }
        },
        {                                                    /* non-filter plug-in class here */
        },
        {                                                    /* comparison ops (not supported) */
        },
        {                                                    /* any enumerations */
        }
    }
};

            在上面的文件中，我们可以看到我们的滤镜含有的两个主要参数：填充颜色 和 不透明度。位于 IMAGE_DIRECT_PARAMETER 结构中，typeInteger 指明它们是整数类型。flagsSingleParameter指明它们是基本类型（具有单一值）。此外，还可以把参数定义为枚举类型，同时把枚举的值域定义放在最后一节中，这里我们对此不做介绍了。

                  

                  滤镜被重新编译后，我们在PS中对它录制一个动作，命名为“测试 FillRed”，录制完成后，可以看到在动作面板上的左侧，出现了对话框选项的CheckBox，我们可以设置播放时是否弹出对话框。我们把FillRed滤镜命令的下拉列表展开可以看到滤镜参数：

                  FillColor: 10

                  Opacity:90

                  请注意参数的名字就是来自于上面的aete资源中的定义的滤镜参数名字属性，这就是我们需要给它定义一个可读的参数名的原因。需要注意的是，由于我们把对话框上三个参数合成为了一个参数，这就使得上面的参数显示是三个参数的合成值（10进制）。因此这里为了看清楚，我就只设置了 R 和 O1，其他参数都为0，这样我们在动作面板看到的参数值就和滤镜的对话框上的参数值是一致的。否则我们看到的将是三个参数合成后的值。

                  最后，是滤镜的源代码下载链接：

                  https://files.cnblogs.com/hoodlum1980/FillRed.rar

                  我的相关文章：

                  《怎样编写一个Photoshop滤镜（1）》

                  《怎样编写一个Photoshop滤镜（2）》