What's New in the MAX 3.0 SDK
See Also: Required Changes to MAX 2.x Plug-Ins for MAX 3.0, What's New in the MAX 2.0 and 2.5 SDKs, Updating MAX 1.0 Plug-Ins to work with MAX 2.x.
Overview
This section provides a general overview of the new capabilities of the 3ds max 3.0 API. New plug-in types, new classes, and new methods to existing classes have been added. In some cases new parameters to existing methods have been added as well.
Any new classes in the SDK begin their Description section with the line:
This class is available in release 3.0 and later only
Any new methods in a class begin:
This method is available in release 3.0 and later only
Newly added parameters to existing methods begin:
This parameter is available in release 3.0 and later only
Newly added data members begin:
This data member is available in release 3.0 and later only
The sub-sections below list some of the major areas of improvement or new capabilities in the SDK. This includes new plug-in types, new parameter map system, new texture map architecture, new keyboard accelerator system, as well as numerous other changes.
New Plug-In Types
The following are the new plug-in types introduced in the 3ds max 3.0 SDK. Each has link to the base class for the creation of that plug-in type.
Rendering Effects
There is a new item under the Rendering menu which displays the Rendering Effects dialog. From this modeless dialog, the user can select and assign a new class of plug-in, called a “Rendering Effect,” which is a post-rendering image-processing effect. This lets the user apply image processing without using Video Post, and has the added advantage of allowing animated parameters and references to scene objects. The base class for these plug-ins is Class Effect. Sample code is available in the directory \MAXSDK\SAMPLES\RENDER\RENDEREEFFECT.
Anti-Aliasing Filters
There is a new plug-in type for filtering and anti-aliasing the image. Documentation for the base class for these filters is in Class FilterKernel. Sample Code is available in the subdirectory \MAXSDK\SAMPLES\RENDER\AAFILTERS.
Shader Plug-Ins
This new plug-in type works with the new Standard material. It allows plug-in developers to add additional shading algorithms to the drop down list of available options (previously Constant, Phong, Blinn, Metal). This was only possible previously by writing an entire Material plug-in (which could be a major undertaking). See the base class for this plug-in type Class Shader for details.
Sampler Plug-Ins
This plug-in type works with the Standard material of release 3. A Sampler is a plug-in that determines where inside a single pixel the shading and texture samples are computed. The user interface of Samplers appears in the Super Sampling rollout in the Sampler dropdown. See Class Sampler for details.
Shadow Generator Plug-Ins
The generation of shadows is now accessible via this new plug-in type. The standard 3ds max mapped and raytraced shadows have been revised to be plug-ins of this form. See Class Class ShadowType and Class ShadowGenerator for details. There is also a handy class for creating shadow map buffers. See Class ShadBufRenderer.
Color Selector Plug-Ins
This new plug-in type provides the user with a custom color picker that appears whenever a standard 3ds max color swatch control is clicked. These plug-ins are selected in the General tab of the Preferences dialog. The color picker chosen is saved in the 3DSMAX.INI file in the "ColorPicker" section so that the choice is maintained between sessions. If the DLL for the selected color picker is not available, it will always default back to the "Default" color picker. See Class ColPick for details.
Global Utility Plug-Ins
These simple utility plug-ins are loaded at boot time, after initialization, but before the message loop starts, and remain loaded. This is how the new 3ds max COM/DCOM interface is implemented. For details see Class GUP.
Ready To Build Plug-In Projects
The 3ds max 4.0 SDK comes provided with an SDK appwizard that can be used with Microsoft Visual C++. This appwizard allows you to quickly generate skeleton source code for a variety of different plugin types and essentially replaced the previous R3_SKELETON projects included in the previous release of the software.
The generated code from the appwizard provides a quick way to start building plugins. Each project follows a standard structure with regard to headers and code files. Developers should find it easy to take this generated code and can start creating plugins without manually setting up the entire project from scratch.
New Example Code for R3 Programming Concepts
The SDK has sample code for demonstrating several programming concepts and exposed APIs introduced in R3. This code can be found in the sub-directories of \MAXSDK\SAMPLES\HOWTO\EXAMPLES. The API exposed by the Morpher modifier is demonstrated in MORPHERAPI. In the directory SCRIPTPLUGIN is a utility that demonstrates SDK access to a scripted plug-in's parameters. Code which demonstrates using the Custom User Interface APIs is in CUI-TEST.
MAXScript SDK
The MAXScript SDK is a set of Visual C++ headers and import libraries that programmers can use to extend MAXScript. The MAXScript SDK source is now a part of the main 3ds max SDK source tree. It is available in the directory \MAXSDK\INCLUDE\MAXSCRPT. In order to use the MAXScript SDK, you'll need to add \MAXSDK\LIB\MAXSCRPT.LIB to your project and add \MAXSDK\INCLUDE\MAXSCRPT to your preprocessor include directories. See the Advanced Topics section MAXScript SDK for documentation on this SDK.
There are two samples programs available in the directory \MAXSDK\SAMPLES\HOWTO\MXS_SAMPLES. These are TESTDLX and MXSAGNI. TESTDLX shows how to add new types of classes to MAXScript. It also shows how to add custom controls. The other is MXSAGNI which shows how to expose globals, struct globals, primitives and struct primitives. It also shows how to add new types of classes like BigMatrix, TrackViewPick, and Physique and Biped interfaces.
There is also sample code in the SDK showing how to add a custom function to MAXScript, add a custom UI element, add a system variable and add a class. For this see the projects in \MAXSDK\HOWTO\R3_SKELETONS\MAXSCRIPTSDK.
COM/DCOM Interface
The COM/DCOM interface available in 3ds max 3.0 may be used to load and save scenes, import files, and drive the 3ds max renderer. The interface for doing this is discussed in the Advanced Topics section COM/DCOM Interface.
Deferred Loading of Plug-Ins
3ds max 3.0 has introduced the concept of delay-loading plug-ins. In previous releases every plug-in was loaded at 3ds max load time. Now, certain plug-ins are only loaded as needed. This results in a smaller memory footprint for 3ds max and shorter load time at startup. The impact of this on developers is that the method ClassEntry::CD() may return a pointer to an instance of class DataClassDesc rather than a full ClassDesc as it did previously. This derived class implements Create() by returning NULL. Developers need to call ClassEntry::FullCD() in order to ensure that the class is actually there. See Class DataClassDesc and Class ClassEntry for information on these methods. For additional details on delay-loading see the Advanced Topics section Deferred Loading of Plug-Ins.
New Parameter Map System
The existing parameter map system remains for backwards compatibility but a new and improved system is available in the 3ds max 3.0 SDK. This system makes user interface coding even simpler than before and allows plug-ins to properly integrate with 3ds max 3.0's Macro Recorder, 3ds maxScript and Schematic View. For details on this system see the Advanced Topics section Parameter Blocks and Maps in Release 3.
Multiple Map Support
New in 3ds max 3.0 is the ability to use more than two texture maps per face of a mesh. Now users may use up to 100. This has impacted how mapping coordinates are stored by the mesh as well as how the color per vertex data is stored. There are corresponding new methods in Class Object and Class Mesh. Also see the Advanced Topics section Working with Meshes (Mapping Channels in Release 3.0 and Later) for additional information.
This has also affect Patches and NURBS. See the sections Required Changes to Patch Related Plug-Ins and Required Changes to NURBS for details.
Access to Scene XRefs and XRef Objects
3ds max 3.0 introduces Scene and Object External References (XRefs). Scene XRefs are stored as complete hierarchies with the XRef scene's root node as a child of the client scene's root node. There are new methods in Class INode to access these Scene XRefs subtrees. There are also two new methods in Class Interface for controlling the scene node traversal. Object XRefs are derived from Class IXRefObject and this class provides access to the Object XRef parameters.
New G-Buffer Capabilities
The G-Buffer has been significantly enhanced for R3. The concept of 'layers' has been added as well as four new channels. The multiple layers of the G-Buffer allow image processing effects to do better anti-aliasing and handling of transparency. The new channels are:
BMM_CHAN_COLOR
This is the color returned by the material shader for the fragment.
BMM_CHAN_TRANSP
This is the transparency returned by the material shader for the fragment.
BMM_CHAN_VELOC
This gives the velocity vector of the fragment relative to the screen, in screen coordinates.
BMM_CHAN_WEIGHT
This is the sub-pixel weight of a fragment.
See Class GBuffer and List of Image (G-Buffer) Channels for details.
New NURBS Related Classes
The NURBS API has been extended and altered in release 3.0. The primary change has been in the way texture surface are handled. See the sub-topic Texture Mapping in the Working with NURBS topic for an overview of the classes. Also see the section Required Changes to NURBS Related Plug-Ins for an overview of the other changes. The new classes introduced in release 3.0 are:
Class NURBSProceeduralSurface.
Access to the File Properties Data
The 3ds max File Properties dialog allows a user to enter various information to be stored in the 3ds max file. Developers can access this information via the SDK. Methods of class Interface provide this access (see the PropertySet methods of Class Interface for details). There is a sample project in the SDK which demonstrates how this is done. See the code in \MAXSDK\SAMPLES\UTILITIES\PROPERTYTEST\PROPERTYTEST.CPP.
New Notifications (Callbacks)
The SDK provides a notification system where a plug-in can ask to receive a callback for events such as the user executing File/Reset, changing the viewport layout, rendering the scene, etc. There are several new types of notifications codes that may be registered in R3. The documentation for Structure NotifyInfo and List of Notification Codes describes them.
Ability For Non-3D Windows to Appear in a 3ds max Viewport
Programs that want to have their user interface appear in a 3ds max viewport (much like Track View and the Asset Manager do) can now accomplish this. See Class ViewWindow for details.
New Keyboard Shortcut System
This new system is used to register keyboard shortcuts in a uniform manner. In 3ds max 3.0 in the Customize / Preference Settings / Keyboard tab dialog there is a section to assign Plug-In shortcuts to commands. For details on how this works see Keyboard Shortcut System. Sample code is available in the directory \MAXSDK\SAMPLES\MODIFIERS\FFD.
New Custom User Interface API
3ds max now allows users the customize the user interface. There is an API that allows developers to do some customization as well. Developers can create their own custom toolbars and tab panels which may be docked or floated. The buttons can run 3ds max keyboard commands and execute 3ds max script commands in addition to the usual custom toolbar functionality (icon buttons, flyoffs, etc.)
There is a sample program in the SDK which demonstrates the use of these API. It's in \MAXSDK\SAMPLES\HOWTO\EXAMPLES\CUI-TEST. Follow the instruction in the comments at the top of the code to build and run this plug-in.
The main classes used in working with the custom UI are:
This existing class has been enhanced to support the new CUI functionality. Toolbars may now support multiple rows, or appear vertically. They may also have macro buttons (added with the MacroButtonData class) which may have icons or text.
When a Toolbar is part of a CUI frame it's called a Tool Palette. Tool Palettes can either float or dock (whereas a Toolbar must be placed by the developer in a dialog using the resource editor). When you want to create a Tool Palette you create a Toolbar (as before) and then you create a CUIFrame and then link the two using a method of CUIFrame.
A Macro Button is a button which can execute either a keyboard macro or a MAXScript macro. This class contains the data and access methods for such a UI button.
This class provides access to the individual windows (frames) that that contain the toolbars, menus, etc.
There is one instance of the CUIFrameMgr and it controls the overall operation of the individual CUI frames. This class has methods for things like docking a tool palette, bringing up the toolbar right click menu, and returns button IDs and window handles.
Since the CUI frame is just a window, it needs a window proc. There is one built into the CUI system, but certain frames may need additional information that is specific to how the frame is being used. For example, the command panel is a CUI frame which can't be resized horizontally. To manage this, the application must install a CUIFrameMsgHandler object. This class has one method, ProcessMessage().
This is the object that provides the position data when the CUIFrameMsgHandler::ProcessMessage() method recieves a CUI_POSDATA_MSG message. The developer creates an instance of this class and implements the GetWidth() and GetHeight() methods which return size information based on the size type and orientation passed.
This class allows a Macro button control to be added to the toolbar.
This class provides access to Macro scripts. Macro scripts (or macros) are scripts that live in buttons and menus in the customizable UI. Methods of this class are availalble to access macros using IDs or category and name strings, methods to edit macro scripts, methods to execute macros, and methods for directory scanning and loading.
This class provides access to a single macro entry. There are methods provided to access the macro ID, name, category, file name, tooltip, UI button text, and the UI button icon. MacroEntries are returned from methods of class MacroDir.
New Custom Slider and Curve Controls
There is a new custom horizontal slider control. This control is functionally similar to the custom spinner control with a few handy features. An example of this control can be seen in the Color Balance Render Effect. See Class ISliderControl for details.
There is also a new custom curve control. An example of this control in the 3ds max user interface can be seen in the Color Map section of the Output rollup of a 2D Texture map. Sample code using these APIs is available in \MAXSDK\SAMPLES\UTILITIES\CCUTIL\CCUTIL.CPP. See Class ICurveCtl for reference information.
New RightClickMenuManager Methods
These new methods let plug-ins add sub-menus to the viewport right-click menu. Developers can call the methods
int BeginSubMenu(LPCTSTR name);
int EndSubMenu();
to start and end sub-menus. See Class RIghtClickMenuManager.
Access to the Track Bar
Directly below the time slider is a new Track Bar, which offers a quick way to manipulate keyframes for selected objects. Keys are displayed on the track bar just like they are in Track View. Developers have access to a class which may be used to manipulate the Track Bar. See Class ITrackBar for details.
New Multiple Viewport Enabled Mouse Proc
This new mouse proc allows drawing in multiple viewports, offsetting from the construction plane, and orthogonal and angle snapping. This is the mouse proc that NURBS uses for curve creation. This allows developers to support orthogonal snapping and angle snapping on creation like the Bezier Line tool does. Also if the user presses Shift while dragging the mouse, the point is snapped to the nearest quadrant (ortho snapping). If the Alt key is held, the point is snapped using the setting of the angle snap system.
Users of this mouse proc need to sub-class from the Class DataEntryMouseProc and implement some virtual methods to use it.
Ability to Replace the 3ds max Load and Save File Dialogs
There are two new classes and two methods of Interface that allow developers to replace the load and save file dialogs with custom ones. See the methods:
virtual void SetMAXFileOpenDlg(MAXFileOpenDialog* dlg)=0;
virtual void SetMAXFileSaveDlg(MAXFileSaveDialog* dlg)=0;
in Class Interface for more information.
Schematic View API
The Schematic View window allows users to review, and perform certain operations on, many of the objects that make up the scene. See the Advanced Topics section on Schematic View for an overview of the API. Developers have access to method for working with Schematic View as part of the following classes:
This class represents an instance of a schematic view window and provides methods for adding nodes and node pointers, refreshing the schematic view, accessing filter bits and updating and controlling the various editors within 3ds max.
This represents a node in the schematic view graph and provides a few methods for querying information about the node.
IGraphRef represents a node pointer in Schematic View.
There is a set of methods in Animatable that can be overridden, all or in part, to specialize the behavior of the schematic view node(s) which represents the Animatable object.
This existing class also has some Schematic View drawing related methods (GetUIInfo() and SetUIInfo()).
Random Number Generator
There is a new class that may be used to generate pseudo-radom number in either floating point or integer format within a specified range. Each instantiation of this class is independent, permitting several uncoupled random number generators to be present in the system at once. See Class Random.
Macro Recorder API
3ds max R3 introduced the concept of macro recording. The macro recorder generates MAXScript code for operations the user performs when running 3ds max. These scripts can then be played back to automate operations inside 3ds max. Since 3ds max is made up of plug-ins there needs to be a way that the plug-ins can record their own changes as the user operates them. This is the purpose of the Macro Recorder API.
Most common operations performed by a plug-in are handled automatically. For example the getting and setting of parameter block values automatically generates script for the Macro Recorder. In such cases a plug-in developer doesn't need to do anything. There are other operations that can't be handled automatically, however. For example a plug-in may have a button in its user interface that internally results in some looping. To generate code to record a loop the methods of MacroRecorder would be used. See Class MacroRecorder.
Access To 3D Studio VIZ Layers
For use with the layer capabilities of 3D Studio VIZ several classes have been added to the 3ds max API. See Class ILayer and Class ILayerManager for details.
New Methods for the IK Master Controller
The new methods provide additional access to the controls. See Class IKMasterControl.
New and Revised Mesh Related Classes
The following classes track various aspects of an edit operation to a mesh. They are the principal means of keeping track of what's going on in the Edit Mesh modifier, and have many standard mesh edits available for use by other plug-ins.
This is a class that represent some kind of change to a mesh. This “delta” can include topological, geometric, map, and/or selection changes. Most standard mesh “edits” available in the Editable Mesh or Edit Mesh interface are available through the MeshDelta SDK, giving developers a powerful way to manipulate meshes while not having to “sweat the details” of maintaining maps to match the mesh changes, updating edge selections, etc.
This class represents the notion of a mesh edit vertex move. The public data members provide the index of the vertex moved as well as the amount of the move in X, Y, and Z.
This class represents the notion of a mesh edit UVW vertex assignment. The public data members provide the index of the vertex as well as the UVWVert.
This class represents the notion of a mesh edit Face Remap, which changes one or more of the verticies a face uses. It can also alter the visibiliy of the face's edge, its hidden state and its material ID.
This class represents the notion of a mesh edit Face Change, which changes the visibiliy of the face's edges, its hidden state and/or its material ID.
This class represnents the notion of the edit mesh Face Smooth operation. This updates the smoothing group infomation in the face.
Similar to the above classes, but used for topological operations in the Edit Mesh modifier and Editalble mesh are the classes below:
Class MeshDeltaUser and Class MeshDeltaUserData
Both Edit Mesh and Editable Mesh have a current "state", which can be modified by MeshDelta objects. In Editable Mesh, this "state" is an actual mesh, while in Edit Mesh, this is one MeshDelta per LocalModData. These are the two new classes which provide a standard interface to these.
VDataDelta is simply a way for a MeshDelta to keep track of per-vertex information.
This class that represents some kind of change to a mesh map. This “delta” can include changes in map vertices and/or faces.
This is a class for caching winged edge lists, face adjacency lists, face and edge clusters, vertex normals, and other derived data about a mesh.
This is a class to maintain chamfer information between several MeshDelta methods.
This is a list of edge "clusters" for a given mesh. A typical application would be in Edit(able) Mesh, where the user has selected a two separate groups of edges on different parts of the mesh and wants to extrude them both, or rotate both around their local centers. Each "cluster" is a contiguous group of selected edges.
Prior to release 3.0, developers could implement the Object::ApplyUVWMap() in their objects, but they haven't had access to the algorithm 3ds max uses to turn the mapping types (MAP_BOX, MAP_PLANE, etc) into an actual vertex-to-mapping-coordinate function. Now this is available as a class, UVWMapper. The mesh ApplyUVWMap() method has been changed to take advantage of this.
The IMeshSelect and IMeshSelectData classes have been extended to support the Editable Mesh and Edit Mesh modifier (not just the Mesh Select modifier).
This class provides access to the Editable Mesh object, Edit Mesh modifier and Mesh Select modifier selection-level data as well as a selection-change-notification method.
This class may be used to get and set the vertex, face, and edge selection state of the Edit Mesh or Mesh Select modifier.
New Interface Classes
The following new interface classes provide access to various objects, modifiers, controllers etc.