Contents
3ds Max SDK Programmer's Guide
About the 3ds Max SDK
Directory Structure
Library File Descriptions
Sample Plug-ins
Animation Plug-ins
Character Studio Plug-ins
Data Import and Export Plug-ins
Material and Texture Map Plug-ins
MAXScript Extension Plug-ins
Mental Ray Plug-ins
Miscellaneous Samples and Plug-ins
Modifier Plug-ins
Object Plug-ins
Particle System Plug-ins
Rendering Plug-ins
Utility Plug-ins
Support for Developers
3ds Max SDK Documentation Online
Basic and Community Based Support
Premium Support - Autodesk Developer Network
SDK Requirements
Using 3ds Max Generated Minidump Files
3ds Max SDK - The Learning Path
Getting Started Writing Plug-ins
Installing the Plug-in Wizard (AppWizard)
Lesson 1: Sample utility plug-in
Lesson 2: The Scene Graph and Nodes
Lesson 3: the reference system
Lesson 4: Animation Controllers
Lesson 5: Geometric Objects
Lesson 6: Parameter Blocks
Lesson 7: Writing .Net Plug-ins
What's New
What's New: 3ds Max 2012 SDK
Major New Features
Incremental Improvements
Upgrading the target .NET framework version to .Net 4.0
Porting Object Plug-ins to Nitrous
Porting Simple Material and Texture Map Plug-ins to Nitrous
Porting Advanced Material and Texture Map Plug-ins to Nitrous
Interface Querying
Known Issues
What's New: 3ds Max 2011 SDK
Major New Features
Incremental Improvements
SDK Change Details
Changes to SDK Documentation
What's New: 3ds Max 2010 SDK
Upgrading to Visual Studio 2008 Service Pack 1
Major New Features
Incremental Improvements
User Interface Updates
Plug-in Upgrade Guide
What's New: 3ds Max 2009 SDK
What's New: 3ds Max 2008 SDK
What's New: 3ds Max 9 SDK
Upgrading to Visual Studio 2005 (Visual C++ 8.0)
Run Time Library Validation
Release Builds Have Asserts Turned Off
Changes to DllMain()
Changes to Module Definition Files(.DEF)
wchar_t is Now Treated as a Type
for() Loop Scoping
Implicit int Type is Invalid
Named Enums
Debugger and Symbols
Manifests
Reference System Changes
Relative Paths
NVIDIA Cg Support
What's New in 3DXI
ParamBlockDesc2 Flags
SuperClassID Cleanup
NoRemap() was Deprecated
MBCS Versus Unicode
Vault and Asset Tracking
Method for Including .lib files
size_t Considerations
Max File Format Change
Overview
Overview: 3ds Max Architecture
Overview: 3ds Max SDK
Overview: Plug-ins
Overview: Class Hierarchy
Overview: Scene Graph and Nodes
Overview: Parameter Blocks
Overview: Reference System
Overview: Animatable Hierarchy
Overview: Time and Intervals
Overview: User Interface
Overview: MAXScript or C++
Best Practices
Undo System Best Practices
General Best Practices
Reference System Best Practices
Memory Management
Smart Pointers (AutoPtr)
AddAppDataChunk and MAX_malloc()
Thread Safety
RTTI and GetInterface()
Exception Safety
Handling WM_NOTIFY Messages
Handling Requests for Interfaces
Correctly Clearing XOR-ed Lines Drawn in the Viewport
3ds Max SDK Features
Working with Plug-ins
Plug-in Architecture
Plug-in Base Classes
Interface Querying
Creating Instances of Plug-ins
Parameter Blocks
Responsibilities of a Parameter Block
Parameter Block UI
Creating a Parameter Block
Describing a Parameter Block
Parameter Block Flags
Parameter Block UI Specification Arguments
Parameter Specification Arguments
Parameter Types
Parameter Flags
Parameter Tags
Parameter UI Control Types
Spinner and Slider Control Types
List Box Control Types
Combo Box Control Types
Saving, Loading, and Deleting Parameter Blocks
Getting and Setting Parameter Block Values
Accessing and Exposing Parameter Blocks
Parameter Block 1
Creating a Parameter Block 1
Loading Old Parameter Data using IParamBlock2
Advanced Parameter Block Topics
Multiple Parameter Blocks
Monitoring Parameter Changes
Sub-Texture Map Parameters
Using Multiple Roll-ups
Scenes and Nodes
Scene File (Max File)
Scene Objects
Scene Graph
Nodes
Nodes and References
Node Parent / Child Relationships
Responding to Node Deletion
Getting the Nodes that Reference an Object
Organizing Nodes
Node Grouping
XRef Scenes and Objects
Named Selection Sets
Layers
Recovering an ILayer or ILayerProperties from an INode
Iterating over Layers by Name
Iterating over Layers by Index
Iterating over Nodes in a Layer
Containers
Container Manager and Container Objects
Container Types
Working with Containers
Assets
Declaring and Representing Assets
Saving and Loading Assets
Enumerating and Exposing Assets
Asset File Path Resolution
Session Paths
Custom Scene Data
Custom Attributes
Custom User Properties
Application Data
Common Scene Tasks
Naming Scene Entities
Reference System
How Plug-ins Observe Reference Targets
Writing Reference Makers
Writing Reference Targets
Creating and Changing References
Deleting References
Loading and Saving of References
Reference Messages
Handling Reference Messages
Viewing Reference Messages
Kinds of References
Strong References
Weak References
Indirect References
Node Monitors
Using Indirect References Instead of Pointers
Indirect Reference Example
Indirect References and Object XRefs
Managing Variable Number of References
Reference Hierarchy Functions
Reference Object Lifetime Management
Reference System Common Tasks
Counting Observers of a Reference Target
Cloning Reference Targets
Guidelines for Changing the Reference Structure
Broadcast Notification System
Modeling
Geometric Objects
How Objects are Drawn in the Viewport
Local Space versus World Space
Deformable Objects
Mappable Objects
Geometry Pipeline System
Pipeline Overview
Pipeline Terminology
Object State
Object State Transformation Matrix
Viewport Rendering and the Pipeline
Pipeline Optimizations
Objects Flowing through the Pipeline
Primitive Pipeline Objects
Objects without Geometry in the Pipeline
Writing Pipeline Compatible Objects
Object Space and World Space
Cache System
Cache Validity Intervals
Object Locking
World Space Modifiers and Object Transformations
Channels
Channel Locking
Channel Copying
Preparing Channels for Modification
Modifiers
Modifier Channels
Modifier Types
Object Modifiers
Geometry Modifiers
Material Modifiers
Selection Modifiers
Simple Modifiers
Topology Modifiers
Whole Object Modifiers
Edit Modifiers
Modifier Compatible Types
Mapping Coordinate Modifiers
Validity Intervals
Modifier Stack Branching
World-Space Modifiers
Adding Modifiers to Objects
Meshes
Mesh Related Classes
Extracting the Mesh from a Node
Meshes and Materials
Mesh Edges
MNMesh Edges
Computing Face Normals
Computing Vertex Normals
Computing Vertex Normals by Weighting
Creating Pipeline-Friendly Meshes
Vertex Color Information
Mesh Stripping
Retrieving Mesh Strip Data
Hardware Mesh Support
Texture Vertices and Texture Faces
Transformation and Rotation
Matrix Representations of 3D Transformations
Matrix Fundamentals
Translation (Moving)
Rotation
Scaling
A Matrix3 as an Axis System
Rotation Concepts
Euler Angles
Handling Sign Flips when Converting a Rotation Controller to an Euler Controller
Node Transformations
Transform Center (Pivot Point)
Node Transformation Matrix
Object Transformation Matrix
Local Transformation Matrix
Object Offset Transformation
Transforming Linked Nodes
Using the Node and Object Offset Transformations
Transform Controller Coordinate Systems
PRS Controllers and Node Transformation Matrices
Emulating Reset Transform and Reset Scale
Shapes and Splines
Shape and Spline Principal Classes
Calling CopyBaseData()
Creating a Spline
Capping a Shape with a Mesh
Capping a Shape with a Patch
Patches and Faces
Principal Classes
Creating a Patch
Patch Interpolation
Patch Interpolator Example
Patch Code Example
Working with NURBS
NURBS Terminology
The NURBS API
Overview of the Principal NURBS Classes
NURBS Base Classes
NURBS Point Classes
NURBS Curve Classes
NURBS Surface Classes
NURBS Texture Mapping
Using the API to Create and Modify 3ds Max NURBS Models
Accessing Details of NURBS Objects
NURBS Curve Continuity
Parameter Ranges for Curves and Surfaces
Materials Assignment and Texture Coordinates
Additional Functions for Working with NURBS
Creating and Retrieving 3ds Max NURBS Objects
Creating Primitive NURBS Objects
Modifying Existing NURBS Objects
Rendering
Materials, Textures and Maps
Principal Classes for Materials and Textures
Standard Materials and Textures
Multi-Materials
Retrieving the Material from a Node
Accessing Material Properties
Material Libraries
Assigning Materials to Nodes in the Scene
Editing Material and Texture Parameters
Function and Macros for Use with Materials
Selecting a Sibling Material
Textures Maps
Mapping Coordinates
Mapping Type (Mapping Group)
Mapping Channels
Categories of Texture Maps
Face-Mapped Materials
Procedural Textures Maps
Bump Mapping
RPF Files and the G-Buffer
Texture Coordinates
Texture Map Indices
Lights
Principal Light Classes
Light Parameters
Global Light Scaling and Tinting
Working with Bitmaps
Principal Bitmap Classes
Creating Bitmaps
Loading Bitmaps
Saving Bitmaps
Multi-frame Files
High Dynamic Range Bitmaps
Custom Bitmap Properties
Memory Management for Plug-ins that Work with Bitmaps
Resolution / Palettes / Pixel Storage Topics
Pre-Multiplied Alpha
Dithering and Filtering
Aspect Ratio
Hot Check Utilities
G-Buffer Image Channels
Error Reporting
Utility Functions for Use with Bitmap Files
Bitmap Gamma Correction
Gamma Preferences
Bitmap Gamma Overview
Changing Bitmap Texture Map Gamma
Cameras
Render Elements
G-Buffers
Extending Render To Texture to Support New Materials
Network Rendering
Posting Messages to Video Post
Mental Ray Integration
Mental Ray Shaders in 3ds Max
Mental Ray Classes
Translation of Texture Map and Materials
Mental Ray Translation System
Automatic Parameter Translation
Manual Parameter Translation
Advanced Parameter Translation
Translation of Object Plug-ins
Programming Hardware Shaders
Hardware Rendered Materials
DirectX 10
Hardware Shader UI Feature
Determining DirectX Version
Accessing the DirectX Device
Parsers and Shader Effect Files
Shader Semantics and Annotations
Supported HLSL Shader Semantics
Supported HLSL Shader Annotations
Supported SAS Shader Semantics
Supported SAS Shader Annotations
Supported Direct3D Texture Formats
Obtaining Shader Parameters
Loading and Parsing Shader Effect Files
Animation, Time, and Controllers
Controllers
Controller API Elements
Point Rotation Scale (PRS) Controller
Constraints
Controllers and Parameter Blocks
Transform Controllers and Nodes
The Undo Mechanism and Transform Controllers
Controller Data Access
Keyframe Key Data for the PRS Controller
Keyframe Data Access Classes and Methods
Keyframe Interpolation
Procedural Controller Data Access
Intervals
Time Functions
Animatables and Sub-Animatables
Animatable Handles
Track View
Track View Key Operations
Deleting Controllers
Animation Track Locking
Trajectories
Reference Messages During Animation
Out-of-Range Type
Viewports and Graphics Windows
Hit Testing
Hit Testing in the Graphics Windows
Using setHitCode and setHitDistance
Sub-Object Hit Testing
Hit Lists
Gizmo Hit Testing using PolyLines
Node Level Hit Testing
Hit Regions
Foreground / Background Planes
Rasterization and Z-Buffers
Geometric Primitives Supported by the Graphics Window
Rendering Modes and Rendering Limits
Viewport Button
Graphics Window Coordinate Systems
Graphics Window Light and Materials
User Interface
Caddy Controls
Action System
Classes Involved in the Action System
Building Action Tables
When to Derive from ActionTable and ActionItem
Registering Action Tables
Keyboard Accelerators and Dialog Messages
Menu Manager
Extending 3ds Max's Default Menus
Menu Context IDs
IMenuBarContext
Units of Measurement
Getting and Setting User Preferences
Custom User Interface Controls
Available Custom Controls
Creating a Rollup Page using Custom Controls
Processing User Input from Custom Controls
Methods and Classes of Custom Controls
Parameter Editing on the Command Panel
Command Modes and Mouse Procedures
Guidelines for Handling Character Strings
Schematic View Window
Schematic View API
Schematic View Events
Schematic View Relationships
Windows Themes Support
Vista Aero Support
Tabbed Dialogs
Processing Controls not Managed by the Parameter Map
Windows Message Filtering
Icons
Adding a Customized, Plug-in Specific Tab to the Ribbon UI
Function Publishing
Principal Function Publishing Classes
The Function Publishing API
What would a Plug-in Publish?
Mesh Example
Mixin Interfaces
Publishing Mixin Interface on Arbitrary Classes
Passing FPInterfaces as Parameters and Results
Core Interfaces
Action Interfaces
ParamMap2 Buttons
The FPInterface Class Hierarchy
Parameter Validation
Exception Handling
Property Accessors
Symbolic Enumerations
Additional ParamType2 Codes for Function Publishing and MAXScript
Parameter/Result Types
Added Base Types
Supported Types
Published Functions and MAXScript
Extending Animatable::GetInterface()
Global Function Publishing API Functions
Using FPInterface::Invoke()
Function Publishing Example
MAXScript Scripting Engine
MAXScript Compiler and Interpreter
MAXScript Expression Parsing
MAXScript Values
The MAXScript Garbage Collector
MAXScript Functions
Exposing a Function to MAXScript
MAXScript Distinguished Values
Local Variables in MAXScript Exposed Functions
Calling MAXScript from C++
MAXScript Global Variables
Wrapping 3ds Max Objects
Instantiating Wrappers
Extracting Wrapped Objects
Handling Deleted Wrapped Objects
Advanced MAXScript Topics
MAXScript Functions with Optional Arguments
Local Value Arrays
MAXScript Marshalling of Function Arguments
Character Studio
Biped Hierarchy
Physique Export Interface
Main Physique Export API Elements
Accessing Physique Vertex Assignments
Finding a Physique Modifier
Using the Physique Export Interface
3DXI
3DXI Overview
3DXI Contrasted with 3ds Max SDK
3DXI Initialization
3DXI Export Entities
3DXI Property Containers
3DXI Scene
3DXI Node
3DXI Objects
3DXI Lights and Cameras
3DXI Helper Objects
3DXI Generic Objects
3DXI Mesh
3DXI Materials and Textures
3DXI Controllers: IGameControl
3DXI Animation Keys
3DXI Splines
3DXI IK Chains
3DXI Modifiers
3DXI Error Reporting
3DXI Custom User Data
The Undo and Redo System
How to Enable Undo and Redo
Undo and Redo Example
Deriving from RestoreObj
Scene State Changes that Cannot be Undone
Flushing the Undo Buffer
Super-holds
Undo Memory Limits
Miscellaneous Topics
Collections
Color Palettes
Plugin.ini
Structure edit_window
Post-Load Callbacks
Parameter Maps
The Relationship between Parameter Blocks and Parameter Maps
Using Parameter Maps
Basic Concepts of Parameter Maps
Deriving from IParamArray
Adding the Roll-up to the Command Panel
Removing the Roll-up from the Command Panel
Backward Compatibility
Creating the Parameter Block and Referencing It
Declaring the UI Variables
Describing the Controls
Providing a Name and Dimension for the Parameters
Setting Up the Parameter Block
3ds Max Initialization and Finalization
COM/DCOM Interface
Snapping
Thread Tools
Working with MFC
Managing Scene States
Inverse Kinematics
IK Concepts
IK Solvers
IIKChainControl
IK System Interfaces
Tips and Tricks
Accessing the Parameter Block of any Plug-in
Generating C++ Code from Mesh Data
Referencing a Global Instance of a Non-plug-in Class
Writing Plug-ins
Building the Sample Plug-ins
Configuring the Development Environment
Hybrid, Debug, and Release Build Configurations
Running Plug-ins
Creating a Plug-in Project
Using AppWizard to Create a New Project
Installing the Plug-in Wizard (AppWizard)
Using the Plug-in Wizard
Manually Creating a New Plug-in Project
Creating the DEF File
Required DLL Functions
Adding a Resource Script to the Project
Adding a String Table
Specifying the Include Files
Specifying the Output File
Plug-in File Extensions
Specifying Library Files for the Project
Plug-in Basics
Generating Class IDs
Class Descriptors
Plug-in Identification
Accessing Core 3ds Max Functionality
Creating and Destroying Plug-in Instances
Loading and Saving Plug-in Data
Creating Parameter Blocks
Exposing Parameter Blocks to 3ds Max
Command Panel Input
Exposing and Managing References
Enumerating and Identifying Sub-Animatables
Viewport Functionality
Implementing Clone in a Plug-in
Plug-in Versioning
Remapping References on Load
Parameter Block Versioning
Adding and Deleting Parameters
Changing Parameter Types
Getting and Setting Parameter Block Version
Supporting Save to Previous
Writing Simple Geometric Object Plug-Ins
Object Creation Methods
Programmatic Object Creation
Handling Mouse Procedures
Dialog Based Creation of Objects
Creating the Mesh
Writing Object Plug-ins
Converting Objects to Compatible Types
Displaying the Object in the Viewport
Writing Modifier Plug-ins
Indicating Required Input Object Types
Indicating Required Channels
Indicating Changed Channels
Performing Object Modification
Using a Deformer
Modifier Validity
Displaying the Modifier Gizmo
Sub-Object Selection
Implementing Sub-Object Selection
Modifier Selection Methods
Sub-Object Selection in Edit Modifiers
Edit Mesh Selection Example
Named Sub-Object Selection Sets
Sub-Object Coordinate Systems
Managing Modifier Parameters
Improving Modifier Responsiveness
Writing Animation Controller Plug-ins
Serializing Controllers
Position Constraint Workflow
Control Virtual Methods
CTRL_RELATIVE and CTRL_ABSOLUTE
Undo and Redo in a Controller
Responding to Changes in Parameters
Making Controllers Lockable
Writing System Plug-ins
Ring Array Classes
Ring Array Slave and Master Controllers
Ring Array References
Ring Array Creation Process
Writing World Space Modifier Plug-ins
World Space Modifier Plug-in Overview
Writing MAXScript Plug-ins
MAXScript Plug-in Basics
Writing .NET Plug-ins
Troubleshooting .NET Plug-ins
3ds Max Assemblies
Using C++/CLI
Using .NET for User Interface
.NET Assembly Loader
.NET Action Items
The Enhanced 3ds Max .NET SDK
Writing Other Plug-in Types
Writing Global Utility Plug-ins (GUPs)
Writing Utility Plug-ins
Writing Exporter Plug-ins
Writing Importer Plug-ins
Writing Image IO Plug-ins
Writing Rendering Plug-Ins
Writing Crowd Behavior Plug-ins
Troubleshooting
Common Problems and Solutions
Debugging 3ds Max plug-ins using Visual Studio
DebugPrint()
Debugging in Release Mode
Debug Builds of 3ds Max
Profiling Plug-in Performance
Geometry Checker
MNMesh Note on Debugging
Advanced Plug-in Topics
Responding to Parameter Edits
Plugging in to 3ds Max SDK Help
Deferred Loading of Plug-ins
3ds Max Install Directory Registry Key
Registry Key Structure
What Happens when Plug-in DLLs are Unavailable
Plug-in Directory Search Mechanism
Plug-in Configuration System
Custom Plug-in Creation Processes
Facilitating Translation and Localization
Upgrading to 64-Bit
Mixing 32-bit and 64-bit Environments
32-bit and 64-bit Max Files
SetWindowLong() and GetWindowLong()
Dialog and Window Procedures
In-line Assembly Code
Using printf