COM/DCOM Interface
See Also: Class GUP.
Overview
The idea behind this COM (Component Object Model) object is to expose the core of 3ds max so applications can invoke 3ds max to generate images. The whole implementation of the COM interface was done as a plug-in itself so developers have the option of enhancing it in any manner they wish. Not just by adding interfaces to this object but also by creating entire new objects using this implementation as a code base. The code is extensively documented and the test "Client Application" is also extensively documented in a way where even developers who don’t have any experience with COM objects can make use of it. For those with experience, the 3ds max COM interface is implemented entirely using ATL which makes it very simple to add and/or modify any aspect of the code.
COM Interfaces and their types are defined in an "IDL" file. They may be found in \MAXSDK\SAMPLES\GUP\COMSRV\COMSRV.IDL.
Registering 3ds max as a DCOM Server
The following steps register 3ds max as a DCOM server:
1) Build \MAXSDK\SAMPLES\UTILITIES\COMSRV.MAK and copy the resulting COMSRVUI.DLU to the 3ds max PLUGINS directory.
2) Start 3ds max and go the Utlity Panel. Choose More and pick COM/DCOM Server Control.
3) If the button in the comand panel says "Register" then click it, or if it says "Unregister", then do nothing (as 3ds max is already registered).
Now 3ds max is registered as a DCOM server and an instance of it can be created from any COM client.
It is also possible to register and unregister 3ds max from the command line. There are two command line options that can be passed to MAX:
3DSMAX -RegisterMAXRenderer
3DSMAX -UnregisterMAXRenderer
The MaxRenderer Interface
This is the main interface exported by this COM object. Through its methods you can load a 3ds max scene, define the parameters for a resulting image, request 3ds max to render any number of frames, collect the resulting images, and so on. The other interfaces defined are support interfaces used by the different methods of the 3ds max Renderer Interface.
Properties
These properties are the same ones found in the 3ds max API. They are exposed here so applications can query or define the different attributes of a scene to be rendered.
HRESULT AnimationStart([out, retval] float *pVal);
HRESULT AnimationStart([in] float newVal);
Sets or returns the frame number defined as the starting frame for the current animation. The frame number argument is a float in order to isolate the foreign application from MAX’ frame granularity. A 3ds max frame can be divided into around 4096 time slices. In other words, it is possible to generate animation images with a 1/(30 * 4096) of a second resolution.
HRESULT AnimationEnd([out, retval] float *pVal);
HRESULT AnimationEnd([in] float newVal);
Same as above but for the last frame of the current animation.
HRESULT RenderFieldRender([out, retval] BOOL *pVal);
HRESULT RenderFieldRender([in] BOOL newVal);
Defines (or gets the current state) if the rendered images will be field rendered.
HRESULT RenderColorCheck([out, retval] BOOL *pVal);
HRESULT RenderColorCheck([in] BOOL newVal);
Defines (or gets the current state) if the generated images will be checked for invalid colors.
HRESULT RenderSuperBlack([out, retval] BOOL *pVal);
HRESULT RenderSuperBlack([in] BOOL newVal);
Defines (or gets the current state) how pure blacks are generated.
HRESULT RenderHidden([out, retval] BOOL *pVal);
HRESULT RenderHidden([in] BOOL newVal);
Defines (or gets the current state) if hidden objects are to be rendered.
HRESULT RenderForceTwoSide([out, retval] BOOL *pVal);
HRESULT RenderForceTwoSide([in] BOOL newVal);
Defines (or gets the current state) if both sides of an object are to be rendered. Usually, just the "outside" is rendered.
HRESULT RenderAtmosphere([out, retval] BOOL *pVal);
HRESULT RenderAtmosphere([in] BOOL newVal);
Defines (or gets the current state) if atmospheric effects are to be rendered.
HRESULT RenderFieldOrder([out, retval] long *pVal);
HRESULT RenderFieldOrder([in] long newVal);
Defines (or gets the current order) the order fields are rendered (if field rendering).
Methods
These methods are a superset of the methods found in the 3ds max API. They encapsulate some of the API functions (specifically those related to rendering) in order to simplify the process as well as to isolate the foreign applications from classes and data not exposed.
HRESULT LoadScene([in] BSTR SceneName);
Loads the given 3ds max scene. Note that the location of the scene is from the perspective of the computer where the 3ds max instance is being created. The use of physical drive letters should only be used if you know the scene file resides in the same computer. In doubt, use UNC path names.
HRESULT SaveScene([in] BSTR SceneName);
The counterpart of the above to save the given 3ds max scene.
HRESULT ImportFile([in] BSTR FileName);
Same idea as in LoadScene() but it deals with non 3ds max files. This can be used to write a "translator" where scene files are imported and then saved as 3ds max files.
HRESULT EnumCameras(void);
Use this to enumerate all cameras defined in a scene. When you request 3ds max to render a scene, one of the arguments you need to pass is the name of the camera to use. This method will return all cameras defined in the current scene. The returned names are collected through the _ImaxRendererEvents() interface defined below.
HRESULT OpenRenderer([in] BSTR CameraName, [in] IMaxBitmapInfo *pBif, [in] BOOL region);
Opens the renderer and prepares it to render. The first argument is the camera name to use. You can enumerate all cameras defined in a scene using the EnumCameras() methods described above. The pBif argument is a pointer to a ImaxBitmapInfo() interface (defined below). This object will define the parameters of the resulting image to be created. The last argument defines if the render will be a full image or just a region.
HRESULT SetRegion([in] short x,[in] short y,[in] short w,[in] short h);
If you are rendering just a region of the image, use this to define the region to be rendered. Given as an example a scene you want rendered at 640x480. If you want to render just the first quarter of the image, you would pass a rectangle starting at 0,0, 320 pixels wide, and 240 pixels high.
HRESULT RenderFrame([in] float Time, [in] float Duration);
You’ve loaded a scene, opened the renderer, now you want to render an image. Use this method to generate the image. The first argument defines the frame you want to render. The second defines the duration of the frame. Render progress is processed through the _ImaxRendererEvents() interface defined below. This method returns immediately. You keep track of the progress through the sink event defined above until you receive a OnRenderDone() event call.
HRESULT CancelRenderer(void);
Cancels the rendering.
HRESULT CloseRenderer(void);
When done, use this to close the renderer.
HRESULT GetLine([in] MAXchannelTypes type, [in] long line, [in] BOOL linear, [out, retval] SAFEARRAY(unsigned char) *psa);
Use this method to collect the image you just rendered. The first argument defines the bitmap layout. You can collect the image in many different formats depending on what channels you requested to be rendered in the ImaxBitmapInfo() argument passed to OpenRenderer(). The second argument defines which line you want to collect. The third argument defines if you want the image to be linear or gamma processing should take place.
HRESULT GetPreviewLine([in] long line, [in] long width, [out, retval] SAFEARRAY(unsigned char) *psa);
Used to collect sub-sampled lines used to maintain a preview of the render process as it is happening.
HRESULT ExecuteMAXScriptString([in] BSTR String);
HRESULT ExecuteMAXScriptFile([in] BSTR Filename);
These are used if you need to request 3ds max to do something and the method for doing this something is not exposed above, you could issue a 3ds max Script command (or a whole 3ds max Script file) in order to accomplish this "something" task. Note: These two calls are untested, and unfortunately, there is no error control.
The _ImaxRendererEvents() sink interface
Use this interface to receive notifications and events from MAX.
HRESULT OnEnumCameras([in] BSTR CameraName);
When you issue a ImaxRenderer::EnumCameras(), OnEnumCameras() will be fired for every camera found in the scene.
HRESULT OnRenderProgress([in] long Done,[in] long Total);
This event will be fired during the render process to update the current progress of the render process.
HRESULT OnRenderMessage([in] BSTR Message);
Same as in above. This event will be fired with message updates describing the current stage of the render process.
HRESULT OnRenderDone();
This event is fired when the render is complete.
The MaxBitmapInfo Interface
This interface is used to define the characteristics of the resulting image generated by MAX. There are only properties. The only one that might need explanation is the Channels() property. Use this to define what types of special channels you want generated. These are in addition to the standard RGBA channels.