Feedback needed - Improving ease of use of 3ds Max SDK

[attilaszabo]

Based on feedback we received so far from plug-in developers, we think they face problems when trying to answer these questions:

a) How to find some functionality in the SDK headers?
- Searching for information in the SDK help either failed to give meaningful results or they didn't even try and went directly to the maxsdk\include folder (browse or grep it).

b) Once found the class or function to be used is identified, and corresponding header was included, what library to link the plug-in against?

- Have you experienced these problems yourself?
- Do you have other SDK usability problems?
- Can you describe your workflow for finding Max SDK classes and methods that you need to use in your plug-in?
- Do you have any suggestions as to how to improve the ease of use of the SDK?

Thanks
-Attila Szabo
3ds Max SDK tech-lead

[Anonymous]

- Do you have other SDK usability problems?
The VS Plug-in Wizard was not designed for anything past VS 7.1. Multiple versions would probably help. One can adjust the wizard to work or work without it but, I thought the idea was to help people concentrate on Max SDK and not be having to learn VS at the same time.

There were no practical examples on how to resolve normals, which need to be transformed but not translated. Same thing for texture coords which have similar handling characteristics.

- Can you describe your workflow for finding Max SDK classes and methods that you need to use in your plug-in?
This consisted of, per situation, combing the SDK help for a function that LOOKED like it was name something common-sense-close toward the information needed from Max. If there was not an example of the function in a practical application then, hours of combing Google hits for "FunctionName(".

- Do you have any suggestions as to how to improve the ease of use of the SDK?
Yes! There were 4 or five different ways of retrieving normals. Even in the SDK's own examples, retrieval methods were per-evaluation-per-vertex. Even if Max can store the normals in a different place per-vertex, it would be nice if a function "pmesh-GetVertexNormal iFace, iVertex" just worked.

The SDK needs a smooth way of "pmesh-GetVertexTangent iFace, iVertex" also.

[Anonymous]

Well if you haven't done it yet (haven't got the 2011 version). Please update the whole material samples to really incooperate the new hardware rendering features and how you can use it in your own materials. The SDK completely used to fail short on that matter or had some really, really out of date example codes (some even went back to DX8.1 days! No one is using that anymore). Also update the SDK Help files on this matter.

(See my recent RANT on this matter).

My workflow is normally check if there is an example in the SDK that does something similar I am trying to achieve or uses a specific feature I want to use. If that doesn't help I try to search in the SDK help or look up some certain class descriptions that I know that might have the functionality I am looking for. The last one requires a certain amount of experience with the SDK.

[Anonymous]

General:
More overview articles that give a better view of what different systems actually use.

Specific:
The documentation of the StdMat shader plugins is really poor.
The asset system has specific documentation, but no general overview. And the p_assetTypeID tag has no docs what so ever.

Feature request:
* An SDK for the raytrace engine used by the light-tracer and the raytrace material would help. As it is now I had to write my own raytracer and raytrace material to implement a specific feature.
* A "SimpleShadeContext" to inherit from that implements most of the common methods so it is easier to make our own specific SC:s if needed.

[Anonymous]

- Can you describe your workflow for finding Max SDK classes and methods that you need to use in your plug-in?

i) Read through 30 pages of the documentation, finding several conflicting methods, some outdated, and try the one that vaguely appears to be newest by writing style.
ii) If that fails, begin searching through the samples for something that was written after 2000 (and if I'm lucky, has a comment in it somewhere) for the thing I'm looking into doing.
iii) Find out that Slate material editor breaks plugin somehow, and isn't documented in the SDK at all.
iv) Give up and cry.

[Anonymous]

Still haven't figured out my Slate woes. About 10 seconds after opening the slate editor, Max crashes. The particular plugin I'm working on (a cool procedural material which generates all manner of Julia set fractals with a lot of editable parameters) seems to crash when slate is the default Mtl. editor, but works fine in the old one. I suspect enable / disable of controls is involved, but only because it's the last thing I haven't tried removing. It is needed from a user's point of view because there are many options which are directly related to which rendering type is selected for the fractal, and without a basis in fractal math and familiarity with coloring methods the interface would be too confusing. Example: When the "Orbit Traps" rendering method is selected, around 12 different modifiers are available in the UI. When "Binary Decomposition" is selected only one modifier is relevant. All of this works (mostly) fine through the documented callbacks in 2010, but crashes in Slate.

Because of the inconsistency of the documentation I can't really say that the plugin is following proper design for this program to the letter, but it has no crashes or memory errors rendering very high res scenes in Max 2010 which take upwards of 20 hours of rendering time per frame on a Quad Core 2 @ 2.8Ghz so I'm still tempted to blame undocumented slate functions for this.

Also, regarding the version specific APIs that are tacked on in each release... I don't know, I'm not trying to be an ass, but it seems like somebody at Autodesk read about the basics of <i>writing</i> classes in C++ without really having an understanding of what they are used for. There should not be new interfaces tacked on in this fashion, it doesn't help *ANYTHING*. It's really weird because there are SDK functions which are in the docs as "Deprecated, stop using " with comment dates of 1998, but considering max breaks plugin compatibility between the yearly versions on a regular basis &#40;especially by adding version specific apis&#41;, why bother doing a slow deprecation? Delete all the old crap, write a separate import / conversion utility for end users loading old .MAX files, and clean this up.

I've been tempted to submit portions of the SDK docs to the thedailywtf.com just so everybody can get a laugh out of them...

[Anonymous]

Just so I'm not a complete ass in this post &#40;yeah, I'm tired, sue me&#41; I'll put up a couple of early test renderings from the material. Nothing fancy in the scenes, just render tests.

And unsurprisingly, attachments don't work on the forum... If autodesk wasn't a monopoly I'd be threatening to switch over to Maya right now... :-&#41;

[Anonymous]

Now I feel the need of a SDK dailywtf I should have kept over the years, but I'm sure none of the questions you're asking us would have been there. I appreciate your concern for the community feedback but your questions are for the Max SDK or C++ newcomers not for senior developers.

Let's face it, the heart of the SDK is rotten, bad designed and full of hacks, we all know that and I don't think the answers to your question will improve anything; they will only postpone the frustration the newcomers will face after they find the class implementation or the lib file they have to link with.

Now I'd like to rand a bit about the SDK, since I find it as a great opportunity to talk to the SDK tech-lead and also I think you knew that by opening a subject of so delicacy, people will start ranting. :&#41;

How can we extend a multi-material, standard material, a blizzard system or the other sample documented nodes without having to copy/paste the entire sample in our projects? There are millions of people having to do this, just because someone couldn't do an interface so we can all use.

Why isn't any way to get a camera matrix that can be changed in order to implement a perspective correction matrix for viewport display?

Why the MAXScript functions that work with an array &#40;append, deleteItem, insertItem etc&#41; are only working with arrays made in MAXScript? None of the C++ array &#40;TAB_XXX&#41; are working, and by working I mean calling SetReference&#40;&#41;/GetReference&#40;&#41; according to the MAXScript function you're calling. You have to hack your way around to make it work &#40;and it's not easy or fun to simulate MAXScript in your plugin&#41;.

Why the automatic mental ray translation fails to translate arrays of color type when you have a texture on the color node, but when you look at the 3dsmax.mi file you see that all Max's shaders are translated with color? To make it work, you have to change color type to shader type.

Why is there a file named mr-notes.txt in the sample directory &#40;hanging around since Max7 or worse&#41; that fails to tell anything about the translation between Max and MR? It not only fails but it's also funny to see something like this inside the file that should bring some light on the translation matter:

MR Utility Function to MAX Utility fcn/class mapping
----------------------------------------------------

&#40;todo, probably helpful to try and show rough equivalents for
various mi_api/mi_xxx functions...note that these probably
won't map nicely...for example, mi_img_xxx functions will
map somewhat to Bitmap and GBuffer functions, but probably
not exactly&#41;

or

Interaction with Mental Ray
---------------------------
-- Versioning

Why is there an Interface class that incorporates all the hacks and features that didn't fit in the classes that make up the design of the System?

When there will be a reliable versioning support for the paramblock2 monster?

I saw an improvement on the hardware material in Max 2011 and that is by "removing" all the useless interfaces like IDX9DataBridge, IDX9VertexShader or IDX9PixelShader. You should know that all the hardware material support in Maya is done with 3 functions &#40;glBind&#40;&#41;, glGeometry&#40;&#41; and glUnbind&#40;&#41;&#41;.

And the last one thing that comes to mind is to not forget that you guys promised a "revolution" in which Max starting with 2010 will load in 26 seconds. :&#41;

[Anonymous]

And the last one thing that comes to mind is to not forget that you guys promised a "revolution" in which Max starting with 2010 will load in 26 seconds. :&#41;

It's because it loads like 300 DLLs on startup that kills its startup performance. I guess it still hasn't changed.

To the devs:

Modularity is nice, to an extent, but you have to consider disk I/O &#40;mainly hard page-faults&#41; when you want startup perf to be good.

Perhaps consider delay loading some stuff, or just combine things into larger DLLs -- which should reduce the number of LoadLibrary calls you have to make &#40;and as a consequence DllMain calls for PROCESS_ATTACH and THREAD_ATTACH &#40;unless you use DisableThreadLibraryCalls&#40;&#41;&#41;&#41;.

[digginc]

Hi guys, the 3ds Max SDK writer here. Sorry about your frustration. We have just opened the 3ds Max SDK survey for this year and would really appreciate your participation. See: http://area.autodesk.com/blogs/chris/important_3ds_max_sdk_survey for a link to the survey and more information.

[Anonymous]

Why the automatic mental ray translation fails to translate arrays of color type when you have a texture on the color node, but when you look at the 3dsmax.mi file you see that all Max's shaders are translated with color? To make it work, you have to change color type to shader type.

Hmm well you seem to achieve more than I can. Automatic translation doesn't seem to work for me at all with 2010. Am I missing something since I made sure that all the internal names match the names in the .mi file I even made sure the order is the same but still I'll get empty values when doing this:

::NeedsAutomaticParamBlock2Translation() {
return true
}

Is there some kind of magic I am missing? Also the example / howto in the SDK is completely misleading since it doesn't do automatic translation but all the comments in the ParamBlock2 description say it would.

[Steve_Curley]

And unsurprisingly, attachments don't work on the forum...

They work fine - if you follow the rules