howtoWriteMaxPlugin

最新推荐文章于 2024-10-17 17:31:39 发布
章木蔚明
最新推荐文章于 2024-10-17 17:31:39 发布
阅读量751
点赞数
文章标签： dll class system allocation microsoft winapi
3ds max sdk插件是以dll形式存在的。通常我们用microsoft visual c++ 来开发。
建立一个新的工程的描述见creating a new plugin project
开发者可以将这些DLL插件存放在任何地方，但是要想法子让3ds max知道到哪里去找这些文件。这部分是在plugin directory seaarch mechanism里讨论的。
插件开发者可以为应用加上在线帮助，并使用望可在max help菜单里访问。细节见plugin help system。
有一个标准的位置供开发者保存插件所需的任何配置文件。这些可能是.ini文件，二进制配置文件或任何需要的文件。详见plugin configuraion system。

标准DLL函数
所有的插件dll都必须实现一套标准的函数：
DLLMain()
LibDescription()
LibNumberClasses()
LibClassDesc()
LibVersion()
这些允许MAX访问、维护在dll内在插件并与之协同工作。这些函数的详情见DLL Functions and Class Descriptors.

重入与线程安全的插件
MAX插件必须是可重入与线程安全的。详在Thread safe plugins.
-----------------------------------------------------
第一类：MAX进行DLL装入、分类、管理插件
包括DLL例程和类描述类（class descriptors提供插件类的信息，用以实现LibClassDesc()函数)
DLL functions: 
DLLMain(HINSTANCE hinstDLL,ULONG fdwReason,LPVOID lpvReserved)
当DLL被装入时由windows调用。该函数也会在时间关键性操作期间被多次调用，如绚染。所以开发者在该函数内要小心谨慎。注意以下的示意代码中，在DLL第一次调用以后只有很少的语句被执行。该函数应该返回TRUE！
----
int controlsInit = FALSE;
BOOL WINAPI DllMain(HINSTANCE hinstDLL,ULONG fdwReason,LPVOID lpvReserved) 
{	
// Hang on to this DLL's instance handle.
hInstance = hinstDLL;
if (! controlsInit) {
	controlsInit = TRUE;
	// Initialize MAX's custom controls
	InitCustomControls(hInstance);
	// Initialize Win95 controls
	InitCommonControls();
  }	
return(TRUE);
}
------
LibNumberClasses()
当MAX启动之后，它找到并装入这些DLLs。然后，它需要有个法子判断DLL中的插件类数目。开发者应当在本函数中提供，例如：
__declspec(dllexport) int LibNumberClasses(){return 1;}
返回值即插件类的个数。
------
LibClassDesc(i)
插件必须向系统提供一个方法以获取插件定义的类的描述器(Class Descriptors)。类描述器向系统提供DLL中的插件类的信息。本函数使系统可以访问类描述器，返回值应该是指向第i个类描述器的指针。（一个DLL中可以有许多个类描述器）。如：
----
__declspec(dllexport)Class Desc * LibClassDesc(int i)
{ switch(i){
    case 0:return &MeltCD;
    case 1:return &CrumpleCD;
    default:return 0;
  }
}
----
关于所返回的类描述器在本主题的最后讨论。
---------
LibDescription()
当包含入口（过程物体、修改器或控制器等）的MAX文件被装入且系统还没有访问它时(如DLL无效)，一个消息被发给用户。当DLL不可用时，系统要求每个DLL返回一个字符串向用户说明情况。
例如，假定用户有一个融化修改器，他将此融化修改器应用到场景中的某个节点上，并保存此文件。当他将这个文件给一个没有这个融化DLL的朋友，这个朋友打开这个文件时，系统将发出一条消息说明文件中的一个入口所依赖的DLL找不到，这个消息可能是“融化修改器。想要请打电话025-1234PLUG-INS”。
DLL必须实现LibDescription()才能向系统提供这个字符串。该函数返回值即为当找不到该DLL时要显示的文字。该字符串也将显示在Summary Info/Plug-In Info... 对话框中。一旦DLL中的一个插件已经在场景中使用过，系统就会把这个字符串保存到max文件里（以便在DLL丢失时显示）。
注意，即使DLL缺席时场景仍然会被打开。MAX保留任何DLL丢失的节点(entities)，这样如果文件被修改并保存然后再在有DLL的系统打开修改后的文件，这些节点仍然存在并链接进场景。不能访问其DLL的入口称为封闭入口(orphaned entities)。
封闭入口将作为其超类(SupperClass)的通用代表导入。该代表将在场景中显示最少的信息。举个实例：如果入口是个修改器，它将在修改器清单中显示自己的名字，但不会显示任何参数。如果没有对象类型信息，那么将在场景中显示为虚物体(dummy)。他们可以被移动、旋转、缩放、链接、组合、删除……任何与节点相关的操作。丢失的控制器只提供不变的默认值，这些值是不可调的。
参考Read Only Plug-Ins部分。通过允许插件工作在只读模式，用户可以自由分发DLL，其他人除非通过了基于硬件锁ID的认证可以运行它，否则使用将受到限制直到购买自己的拷贝。以下是该函数实现的一个例子：
__declspec(dllexport) const TCHAR *
LibDescription(){
  return _T("Melt Modifier. call 1-800-plug-ins to obtain a copy");
}
----------------
LibVersion() 
开发者必须实现一个函数以便系统处理不同版本的3DS MAX 插件DLL。因为MAX体系与插件的关系如此之紧密，系统有时候需要阻止插件的老版本被调用。要使MAX能够完成它，DLL必须实现一个名为LibVersion()的函数。这个函数只简单的返回一个预定义的常量，这个常量表明在插件编译时系统的版本。未来版本的MAX可能更新该常量，而老的DLL总是返回以前的值。该函数使得系统可以检查任意一个DLL是否已经被装入，如果是这样则显示一条消息。
__declspec(dllexport) ULONG 
LibVersion(){return VERSION_3DSMAX;}
注意：开发者可以用下面的全局函数获取该值：
DWORD Get3DSMAXVersion();
返回正在运行的MAX版本被编译时/maxsdk/include/plugapi.h文件中包含的VERSION_3DSMAX宏定义的状态
-----------
总结
插件必须实现这五个函数：DLLMain(),LibNumberClasses(),LibClassDesc(i),LibDescription(),LibVersion()。这些函数允许系统取得DLL中插件的信息。

下面是有关必须被LibClassDesc(i)返回的类描述器的资料。

----------------------------
类描述器Class Descriptors
类描述器向系统提供DLL中插件类的信息。类描述的一个方法负责分配插件类的新实例(Create)。开发者通过从ClassDesc衍生一个子类并实现若干方法成员来建立类描述器。下边是个简单的类描述器及其静态实例的例子。
----
class MeltClassDesc:public ClassDesc{
  public:
    int IsPublic(){return TRUE;}
    void * Create(BOOL loading=FALSE){return new MeltMod();}
    const TCHAR * ClassName(){return _T("Melt");}
    SClass_ID SuperClassID(){return OSM_CLASS_ID;}
    Class_ID ClassID(){return Class_ID(0xA1C8E1D1,0xE7AA2BE5);}
    const TCHAR * Category(){ return _T("");}
}
static MeltClassDesc MeltCD;
----
下面讲讲六个类描述器方法成员：IsPublic(),Create(),ClassName(),SuperClassID(),ClassID()和Category()。
--------
IsPublic()
该方法返回一个布尔值。如果插件可以被用户选取和指派，正是常见的情况，返回TRUE。某些插件可能是同一DLL的实现的其它插件私有专用的，并不出现在清单供用户选择。这些插件将返回FALSE。
------
Create(BOOL loading=FALSE)
MAX在需要得到一个指向插件类的新实例的时候调用该方法。例如，如果MAX从磁盘打开一个包含前边用过的插件的文件，它将调用插件的Create()方法。插件负责分配一个插件类的新实例。在上边的例子的是用一个"new"操作简单实现的。
Create()的可选参数是一个标识表明要创建的类是否将从一个磁盘文件中装入。如果该标识为TRUE，插件可以不必做任何初始化工作，因为装入进程将会处理它。见Loading and Saving。
当系统需要删除一个插件类的实例时，它会调用Animatable的DeleteThis()方法。插件开发者必须实现该方法。因为开发使用new操作分配内存，他/她(?)也应该用delete操作释放之。如开发者可以如下实现DeleteThis()：
void DeleteThis(){delete this;}
进一步的细节参考Memory Allocation。
----
ClassName()
该方法返回类的名字。这个名字将出现在MAX用户界面的插件按钮上。该方法也在调试时显示类的名字。
-----
SuperClassID()
该方法返回系统预定义的常量，该常量表示插件类是从哪个类衍生来的。例如，弯曲修改器返回OSM_CLASS_ID。这个超类ID被所有对象空间修改器使用。其它的超类ID例子有：CAMERA_CLASS_ID,LIGHT_CLASS_ID,SHAPE_CLASS_ID,HELPER_CLASS_ID,SYSTEM_CLASS_ID。完整的清单见List of SuperClass ID。
----
ClassID()
该方法必须为对象返回一个唯一性ID。SDK中包含一个生成这种ClassID的程序。使用该程序为你的插件创建ClassID是非常重要的。如果如果你使用任何一个例子程序的源代码来建立自己的插件，必须改变已经存在Class_ID。如果不这样，将会出现冲突。如果两个ClassID冲突，系统将加载它找到的第一个（并将在试图加载第二个时显示存在Class_ID冲突。）
一个Class_ID包含两个无符号的32位整数。建构函数为每一个赋值，如Class_ID(0xA1C864D1,0xE7AA2BE5)。参见Class Class ID。
注意在MAX使用的插件样本代码将类ID第二个32位整数设为0，只有与MAX一起发售的内建插件才可以这样做。所有的插件开发者都应该同时使用两个32位整数！还有，确保你使用SDK提供程序建立类ID，这可确保两个插件类之间不会冲突。要生成一个随机的Class_ID并可选的将其拷贝至剪帖板中，单击KSD Help|DLL Function and Class 部分的Generate a Class ID。
----
Category()
在建立面板底部下拉选单选择类别。如果设成已经存在的类别（如，Standard Primitives, Particle System等)，插件将会出现在那个类别里。开发者不应该加到MAX提供的类别里（见下边的注释）。如果类别还不存在，则将被创建。如果插件不需要出现在清单中，它可以简单的返回一个null字符串_T("")。Category()也被按钮设置对话框中用于插件分类。

重要说明：MAX体系在Create分支面板里有每类12个插件的限制。为预防每个类别有太多插件的问题，开发者应该总是为自己的插件建立一个新的类别而不是使用一个MAX标准插件已经使用的类别。注意早于1.2版本的MAX在每个类别有多于12个按钮时会崩溃。
-----------------------------------------------------
第二类：管理过程物体创建过程并编辑其参数
这部分讨论以下方法：GetCreateMouseCallBack(),proc(),BeginEditParams(),EndEditParams(),GetValue(),SetValue,NumSubs(),SubAnim(),SubAnimName()。
---
当MAX用户将要建立一个新的过程物体时，系统会调用插件的一个方法接管创建阶段的用户输入活动。插件可以任意实现其用户界面，但必须向MAX提供一个途径与用户交互过程联系。插件要实现GetCreateMouseCallBack()函数以向MAX提供该途径。这个函数返回一个指向CreateMouseCallBack衍生类实例的指针。这个类有一个proc()方法，程序员在这个函数里定义物体创建阶段的用户交互活动。系统实际上需要一个函数指针，这个函数是由插件实现可以被系统调用。
参考sphere_c.cpp源代码。

插件必须实现一些方法以处理用在命令面板中的输入。
插件要负责实现从Animatable类继承来的两个方法，这两个方法用来处理用户在命令面板中的输入：BeginEditParams()和EndEditParams()。Begin在用户可以编辑实体参数时由系统调用（物体创建或修改已经存在的实体时都可能调用），它负责向面板里添加卷展栏并将其注册到系统中。加入卷展栏函数带有一个Dialog Proc参数。这个对话处理过程控制用户与对话框控件的交互活动。
过程球体的例子使用了参数映射机制来简化开发者与管理用户界面控制相关工作任务。参数映射被用于管理UI交互活动。见参数映射。
End方法则在用户结束编辑一个物体的参数时被调用。系统将传递一个标识给EndEditParams()以指示卷展栏是否应该删除。如果为TURE，插件必须注销卷展栏，并将其从面板中删掉。在某些情况，物体的卷展栏应该保留在命令面板里。例如如果用户已经完成一个过程球体的建立，它的EndEditParams()方法被调用。然而用户可能希望建立另一个球，这样开发者不可以立刻移走卷展栏。这样用户界面不会因为删除后立刻加回来而闪烁。
----------
参数映射《这部分对于理解例子及简化开发相当有用，所以列入基本内容》
概述
参数映射用于最小化插件管理用户界面参数所需的编程工作。一个简单插件，如过程球体，拥有由类似微调控件