Creating a New Plug-In Project
See Also: Plug-In Directory Search Mechanism, Building the Sample Files.
Overview
This topic presents step by step instructions on how to create a project file for a 3ds max plug-in.
Note: The 3ds max 2.0 SDK now includes a set of AppWizards to create projects for many of the standard plug-ins. Currently it supports: Atmosphere, Anti-Aliasing Filters, Color Selector, File Import, Front End Controllers, Global Utility Plug-Ins, Image Filter / Compositor, Materials, Modifiers, Procedural Objects, Rendering Effects, Textures 2D, Samplers, Shaders, Shadow Generator, Textures 2D, Textures 3D, Track View Utility, and Utility plug-ins.
Using these wizards makes it much easier to create new projects. In addition to setting up most of the compiler / link settings they create CPP files containing the basic class methods that need to be implemented.
To install the AppWizard, copy the \MAXSDK\HELP\SDKAPWZ.ZIP file to the Developer Studio Template directory. For example, copy it to the \Microsoft Visual Studio\Common\MSDev98\Template directory. Then simply unzip the file. The next time you start VC++, from the File / New ... menu, you may choose 3ds max Plugin AppWizard and follow the onscreen prompts. The AppWizard has online help available but the steps are very self explanatory.
If you want to create a plug-in project 'by hand', the process is described next.
Beginning a New Project
To create a new 3ds max plug-in project from within Microsoft Developers Studio follow the steps below:
1 From the File pulldown menu choose New...
2 From the New dialog make sure the Projects tab is selected.
3 Select Win32 Dynamic Link Library from the list of project types.
4 In the Location: box enter the path to where you want the project directory created (for example C:\MYPLUGS).
5 In the Project Name: box enter the name for the directory and plug-in project (for example PRJNAME). A new directory with this name will be created as a sub-directory of the directory entered in the Location: box. The starter project files will also use this name.
6 Press the OK button to exit the dialog.
7 At the prompt What kind of DLL would you like to create? select A simple DLL project and press the Finish button to exit the dialog. Press OK at the next dialog to complete creating the initial files.
Result: Developer Studio creates a new directory and puts starter OPT, DSP, DSW, MAK, and NCB files in this directory. These files are explained below
PRJNAME.DSP -- This is the project file used within the development environment. In previous versions of Visual C++ this file extension was .MAK. It stores the information specific to your project. There will be a separate .DSP file for each project you create. .DSP files are not compatible with NMAKE. You must export a makefile to build with NMAKE.
PRJNAME.DSW -- This is the workspace file used within the development environment. It organizes all the projects into a single workspace.
PRJNAME.NCB -- This is the No compile Browser file. It contains information generated by the parser which is used by ClassView, WizardBar, and Component Gallery. If the file is accidentally or deliberately deleted, it is automatically regenerated.
PRJNAME.OPT -- This is the workspace options file used within the development environment. It stores all the user options you create for your workspace, so that each time you open the project workspace it has the look and feel you want and includes any customizations you have made.
PRJNAME.MAK -- The project makefile.
Creating and Adding DEF and CPP files to the Project
When you create a 3ds max project using the Microsoft Developer Studio, you also need the following file types:
CPP -- The C++ source code.
DEF -- The module-definition file. A module-definition file is an ASCII text file containing one or more module statements that describe various attributes of a DLL. A DLL requires a DEF file to create an import library (LIB) file and an export (EXP) file. The linker uses the import library to build any executable module that uses the DLL and uses the export file to build the DLL file.
You now need to create the DEF file and edit the CPP file. It is usually most convenient if these files reside in the same directory as the DSP file. In the instructions shown below it is assumed your plug-in is called MYPLUGIN.
1 From the File menu choose New. . .
2 From the New dialog choose the Files tab, check the Add to project checkbox, enter the C++ source code file name in the File name: box (for example MYPLUGIN) and select C++ Source File. This brings up a new text file window where you'll add your source code. You can begin the CPP file with the standard 3ds max include file. This is done by adding the following line to the CPP file:
#include "MAX.H".
Next you need to create the DEF file.
1 From the File menu choose New. . .
2 From the New dialog choose the Files tab, check the Add to project box, enter the DEF file name in the File name: box (for example MYPLUGIN.DEF), select Text File and press OK. This brings up a new text file window where you'll edit the DEF file text.
3 Copy the text shown below from this help file into your new text window. This is the basic structure of a DEF file.
LIBRARY MyPlugIn
EXPORTS
LibDescription @1
LibNumberClasses @2
LibClassDesc @3
LibVersion @4
SECTIONS
.data READ WRITE
4 You'll need to perform a single edit to this DEF file to work with your project. The only thing you need to change is the Library name. Simply change it to the name of your DLL. Do not include a file name extension. As shown above the library name is MyPlugIn.
Adding a Resource Script to the Project
You now need to create a Resource file. The resource has an extension of RC.
RC -- The resource file. A resource is binary data that a resource compiler adds to an application's executable file. The data in a resource typically describes an icon, cursor, menu, dialog box, bitmap, etc. Any rollup pages or dialogs you create to implement your user interface will be stored in the RC file. The resource compiler will generate an include file which you must include in your source file.
To create the resource file follow these steps:
1 From the File menu choose New. . .
2 Choose Resource Script.
3 In the File name: box enter your resouce name (for example MyPlugIn.RC).
Result: A resource script window will pop up.
You now need to add a dialog template to this resource script.
1 From the Insert pull down menu choose Resource. . .
2 From the Insert Resource dialog choose Dialog and press New.
Result: A default dialog will pop up.
1 Right Click on the dialog box itself, and from the popup menu choose Properties...
2 In the ID: field enter the ID for the dialog, for example IDD_MYPLUGIN
If your dialog is for use in the command panel or materials editor (not a floating dialog), follow the steps below:
3 Click on the Styles Tab
4 From the Style: drop down list choose Child
5 From the Border: drop down list choose None
6 Close the Properties dialog box and resize the plug-in dialog frame size to a width of 108 units. This is the standard width for the command panel in 3ds max for use in the United States. You can see the size displayed in the lower right corner of the IDE. If you are creating a material or texmap plug-in whose interface shows up in the materials editor dialog the proper width is 217 units. If you're doing an atmospheric or renderer plug-in the correct width is 212 units. If you are creating a dialog that will not be used in the command panel you may, of course, use any size.
Result: You have a dialog template to which you may add controls. For use in the command panel you may wish to delete the OK and Cancel buttons.
When you compile the RC file an include file is generated. The default name is resource.h. This file will be included in your CPP source file to specify the resource ID's. To add the include file to your CPP file edit the CPP file and add the line:
#include "resource.h"
Adding a String Table
Now you need to add a string table to your project. This allows you to put your literal strings into a table for easier translation to other languages. Rather than searching your text for literal strings you can simply change them in the string table. The sample code in the SDK uses this technique to manage strings. To add a string table, do the following:
1 From the Insert pull down menu choose Resource...
2 Choose String Table and press the New button.
Result: You have added the string table to your project.
When you want to add a literal string to your plug-in enter the value into the string table and then use the GetString() function to load that string. To enter the value you simply double click on an empty slot in the table and enter an ID (the ID passed to GetString()) and a Caption (the text). Consider the Animatable::GetClassName() method as an example.
Without the string table, the code would be written:
void GetClassName(TSTR& s) { s = _T("Ring Array"); }
With the string table, it would be written:
void GetClassName(TSTR& s) { s = GetString(IDS_DB_RING_ARRAY_CLASS); }
The GetString() function loads the string from the table and returns a pointer to it. You need to include this function, listed below, in your CPP source file:
TCHAR *GetString(int id) {
static TCHAR buf[256];
if (hInstance)
return LoadString(hInstance, id, buf, sizeof(buf)) ? buf : NULL;
return NULL;
}
For more information see the Advanced Topics section on Globalization.
Specifying Output and Include File Settings
You now need to specify the output file name. This is the name of the DLL created. You specify the output file name for your plug-in using the procedure below:
1 From the Project pull down menu choose Settings... Make sure all the configuration are being changed by selecting All Configurations from the Settings For: dropdown list.
2 From the Project Settings dialog box choose the Link Tab.
3 Under Output file name: Enter the path to 3ds max plug-ins and your file name. For example \3DSMAX\STDPLUGS\MYPLUGIN.DLO
Result: When the project is compiled and linked successfully, the DLL is written to this location.
The example above (MYPLUGIN.DLO) is the extenstion typically used by procecural object plug-ins. For a list of the standard filename extensions for all plug-ins see Plug-In Directory Search Mechanism. Note that 3ds max will only load DLLs that use these standard extensions.
You now need to specify the path of the include files for the SDK:
1 From the Project Settings dialog box choose the C/C++ Tab.
2 From the Category: drop down list box choose Preprocessor.
3 Under Additional include directories: enter the path \MAXSDK\INCLUDE.
You also need to add COMCTL32.LIB which is not included by default by Visual C++ in the list of libraries to link.
1 Still within the Project Settings dialog box choose the Link Tab (you may need to scroll to see it).
2 In the list of Object/library modules add COMCTL32.LIB to the list of existing choices.
3 Select OK to exit the dialog.
Updating the Project Configurations
A new plug-in project contains two default configurations. These are named Win32 Release and Win32 Debug. The sample code that comes with the 3ds max SDK has an additional configuration: Win32 Hybrid. This section discusses the need for these different configuration.
There are three conditions for plug-ins working with MAX. These are:
1) Release 3ds max and Release Mode (non-debug) plug-ins. When you create a plug-in for general distribtion you'll compile in Release mode.
2) Release 3ds max and Debug Mode plug-ins. While developing a plug-in and using source code level debugging you'll compile in Hybrid mode.
3) Debug 3ds max (only registered developers have access to this special version of MAX) and Debug Mode plug-ins. While using the special Debug SDK, and Debug 3ds max you'd compile in Debug Mode.
In Microsoft Developer Studio the Debug and Release C runtime libraries use different heap management. This means that allocating an object in debug mode and de-allocating it in release mode (and vice versa) can cause a crash. Most developers will work with a version of 3ds max compiled in Release mode. Thus it uses the run-time libraries called Multithreaded DLL. Plug-Ins that work with this version of 3ds max need to match this run-time library. If they don't crashes will occur.
To prevent this from happening you need to create a new configuration and change some of the settings of the existing configurations.
To create the Win32 Hybrid configuration follow these steps:
1 From the Build menu choose Configurations... and then choose Add....
2 Enter Hybrid in the Configuration edit box then choose Win32 Debug from the Copy settings from: list box and press OK and then Close to exit the Configurations dialog. This creates a new Hybrid configuration using the same initial settings as the Win32 Debug configuration.
3 From the Project menu choose Settings....
4 From the Settings For: section choose the Win32 Hybrid configuration.
5 From the C/C++ tab, under the Categories: drop down list choose Code Generation.
6 From the Use run-time library: drop down list choose Multithreaded DLL.
7 Choose the General tab of the dialog.
8 In the edit boxes under both Intermediate files: and Output files: enter Hybrid.
9 Select OK to exit the dialog.
Now update the Win32 Release configuration:
1 From the Project menu choose Settings....
2 From the Settings For: section choose the Win32 Release configuration.
3 From the C/C++ tab, under the Categories: drop down list choose Code Generation.
4 From the Use run-time library: drop down list choose Multithreaded DLL.
5 Select OK to exit the dialog.
Now update the Win32 Debug configuration:
1 From the Project menu choose Settings....
2 From the Settings For: section choose the Win32 Debug configuration.
3 From the C/C++ tab, under the Categories: drop down list choose Code Generation.
4 From the Use run-time library: drop down list choose Debug Multithreaded DLL.
5 Select OK to exit the dialog.
Result: You now have three configurations available, each used for a different purpose. When you create a plug-in for distribution to the public use your Win32 Release configuration. During development of the plug-in when you want to use source level debugging use the Win32 Hybrid configuration. If you are a registered developer using the special Debug SDK and Debug 3ds max then use the Win32 Debug configuration.
Specifying Library files for the Project
You will also need to add the 3ds max library files (LIB) to the project. The LIB files required varies depending on the type of plug-in that is being created. Here is the list of the available library files and their use:
ACAP.LIB
The Call Attributed Profiler library. When a plug-in is using the profiler to test performance this library is required. See the Advanced Topics section on Debugging for more information on profiling.
BMM.LIB
Bitmap manager library. Image loader / saver plug-ins, and those that deal with bitmaps require this library.
CLIENT.LIB
Network rendering client library. This one is used internally for network rendering. A plug-in developer won't use this library.
CORE.LIB
Functions exported from MAX. All plug-ins use this library.
EDMODEL.LIB
The NURBS library. Plug-Ins that want to use the NURBS API require this library.
EXPR.LIB
Expression library. Plug-Ins that use the mathematical expression parser (Class Expr) require this library.
FLILIBD.LIB
FLILIBH.LIB
FLILIBR.LIB
Flic file (FLI/FLC) libraries (debug, hybrid, and release versions). Plug-ins that work with FLI/FLC files require the appropriate version of this library. Plug-Ins for release (using the Win32 Release configuration) should use FLILIBR.LIB. Plug-Ins used for source level debugging should use FLILIBH.LIB. Registered developers using the special 3ds max Debug SDK should use FLILIBD.LIB.
FLT.LIB
Filters library. Image Filter plug-ins use this library.
GCOMM.LIB
This library is used internally.
GEOM.LIB
Geometry library. Procedural objects, modifiers, controllers, and utility plug-in use this library.
GFX.LIB
Graphics library. Plug-ins that use MAX's GraphicsWindow calls require this library.
LVSIO.LIB
This is a library designed for reading and writing the Lighscape files.
MAXSCRPT.LIB
Users of the MAXScript SDK require this library.
MAXUTIL.LIB
Utility library. All plug-ins use this library.
MESH.LIB
Mesh library. Plug-Ins that call methods of MAX's Mesh class require this library.
MNMATH.LIB
The 'Minnesota Math' library. Plug-Ins that use the MNMesh and related classes require this library. See Class MNMesh for details.
PARAMBLK2.LIB
The Parameter Block 2 library. Plug-ins that use the parameter block / map system introduced in R3 require this library.
PARTICLE.LIB
Particles library. Plug-ins that relate to particle systems use this library.
PATCH.LIB
Patch library. Plug-ins that deal with Patch objects use this library.
RENDERUTIL.LIB
Render utilities library. It includes the implementation of Quantizer and ColorPacker methods.
TESSINT.LIB
Tesselation library. Plug-ins that deal with the tesselation of NURBS or patches use this library.
VIEWFILE.LIB
This is the file viewer library used by VIEWFILE.DLL.
To add the library files to the project follow these steps:
1 From the Project menu choose Add To Project then Files...
2 Change the Files of type: drop down list to Library files (.lib).
3 Choose the required LIB files from the list (from the \MAXSDK\LIB directory) (you may Ctrl click on them to select more than one). Select OK to exit the dialog.
Result: The LIB files are added to the project.
Note: You may remove the files ODBC32.LIB and ODBCCP32.LIB which are included by default but not needed.
Finishing Up
To complete the new project creation follow these steps:
Since you'll likely need to spend time debugging the Hybrid configuration should be your initial choice. When you've finished development and want to create your DLL for distribution change this to Win32 - Release and rebuild. To set your default configuration to Hybrid do the following.
1 From the Build menu choose Set Active Configuration...
2 Choose Win32 Hybrid and select OK to close the dialog.
Now you need to update the project dependencies and save your work.
1 From the Build pull down choose Update All Dependencies... and choose the all your configurations using the check boxes and then select OK.
2 From the File menu choose Save Workspace to save your new project.
Disabling Exception Handling
This step is not necessary, but developers may wish to disable exception handling for their plug-ins. This can be done using the Project Settings dialog, C++ Tab, C++ Language category and un-checking the Enable exception handling box. This makes the code both smaller and faster.