COM/DCOM Interface

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.VCPROJ and copy the resulting COMSRVUI.DLU to the 3ds Max PLUGINS directory.

2) Start 3ds Max and go the Utility 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 3ds 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.

AnimationStart() - 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 3ds 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.
AnimationEnd() - Same as above but for the last frame of the current animation.
RenderFieldRender()- Defines (or gets the current state) if the rendered images will be field rendered.
RenderColorCheck() - Defines (or gets the current state) if the generated images will be checked for invalid colors.
RenderSuperBlack() - Defines (or gets the current state) how pure blacks are generated.
RenderHidden() - Defines (or gets the current state) if hidden objects are to be rendered.
RenderForceTwoSide() - Defines (or gets the current state) if both sides of an object are to be rendered. Usually, just the "outside" is rendered.
RenderAtmosphere() - Defines (or gets the current state) if atmospheric effects are to be rendered.
RenderFieldOrder() - 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.

LoadScene() - 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.
SaveScene() - The counterpart of the above to save the given 3ds Max scene.
ImportFile() - Similar to 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.
EnumCameras() - 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.
OpenRenderer() - 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.
SetRegion() - 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.
RenderFrame() - 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.
CancelRenderer() - Cancels the rendering.
CloseRenderer() - When done, use this to close the renderer.
GetLine() - 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.
GetPreviewLine() - Used to collect sub-sampled lines used to maintain a preview of the render process as it is happening.
ExecuteMAXScriptString() - 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 3ds Max.

OnEnumCameras() - When you issue a ImaxRenderer::EnumCameras(), OnEnumCameras() will be fired for every camera found in the scene.
OnRenderProgress() - This event will be fired during the render process to update the current progress of the render process.
OnRenderMessage() - This event will be fired with message updates describing the current stage of the render process.
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 3ds 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.