Ray Dream Studio Extension Programming with C++ Builder 4

Note: This entire page is somewhat obsolete, since Metacreations has gone out of business, and Eovia now produces Carrara, the successor to Ray Dream Studio. Eovia has not released a plug-in SDK to the public, so I can't update my extension to work with it yet, or update this page to comment on the process.

Ray Dream Studio is a 3D design and rendering package made by Metacreations. Third-party developers can write extensions to the program using the SDK that comes with it. The SDK contains documentation, source files and examples.

The program was originally developed on the Macintosh, and the SDK still has a significant Mac bias. Even when PC development is supported, the SDK assumes that the developer is using Microsoft Visual C++. I use Borland C++ Builder 4. Ray Dream extensions can be written with Builder, but it required a lot of experimentation to make it work. This page documents the techniques I've used so far for any other Builder users out there who also are interested in Ray Dream extension development.

Programming Ray Dream Extensions on a Win32 System

Because of the Mac bias in the SDK, Win32 programmers (regardless of compiler package) are still 'second class citizens'. If you want to program RDS extensions using Builder, you should first read Eric Winemiller's very good page on using the Ray Dream SDK on Win32 systems. Pay particular attention to the sections regarding resources - they are the hardest part of development on a Win32 system. Even with the information in the SDK and on Eric's page, resource development on Win32 systems is still only marginally satisfactory.

C++ Builder 4 Tips

These tips are what worked for me. There may well be other, more elegant ways of accomplishing the same thing. Please e-mail me if you have suggestions.

Use the command-line tools

I initially made the extension by starting a new project in the Builder IDE, choosing the DLL option. After getting everything else figured out, the project compiled fine, the right functions (with unmangled names) were being exported from the DLL, but RDS totally ignored the extension. I deleted a few USEUNIT statements and the #include <vcl.h> directive from the main cpp file and used the command line tools to compile the project. It then worked perfectly, although I have no idea why switching to the command-line tools made a difference.

The command-line tools can initially be intimidating, and the command-line tool options are not documented in the command-line tools help file, but (rather confusingly) in the main C++ Builder help file. I've included the makefile I finally used in the download package (see below).

Change header files to use <ole2.h>

The header files included with the SDK refer back to a file "Rcompobj.h" which contains declarations of OLE functions that conflict with those found in the <ole2.h> file supplied with Builder 4. I solved this problem by substituting <ole2.h> for "Rcompobj.h" in the appropriate include files, which I saved with "_bcb" appended to their original names (e.g. 3DCotype_bcb.h). I then changed the files that #include the first group of headers so that they now #include the "_bcb" version of the files. The second group of files was also renamed, and the change was propagated through the headers. I also made a similar change in the file 3DCofail.cpp, renaming it to 3DCofail_bcb.cpp and compiling and linking it with the rest of the code (the 3DCofail.lib file is for Visual C++ and thus useless with Builder).

The affected files are:

plus all of the include files for the individual extension types (e.g. I3DExsha_bcb.h for shaders). In all the cases that I have converted so far, the change in this last type of file consists of changing the #include "I3DEx.h" statement to #include "I3DEx_bcb.h"

You should verify that there are no other include statements in the file and let me know if you find any.

Fix the STDAPI macro in exported function declarations

The above fix was not the end of the problems with the header files. It turns out that when doing Win32 programming, Visual C++ doesn't use the __export keyword. There are some older files from Microsoft in the C++ Builder 3 include directory in which an #if defined(__BORLANDC__) directive took care of this, but apparently when they wrote the <ole2.h> group of header files, Microsoft assumed that everyone was programming with Visual C++, so they didn't have to worry about this anymore.

The problem affects the functions that need to be exported from the DLL to make it a COM server. I fixed the problem by defining the macro

#ifdef __BORLANDC__
#define STDAPI_FIX __export
#define STDAPI_FIX

and then putting it in the declarations for the exported functions:

STDAPI STDAPI_FIX DllInitRDCom(IShUtilities* shellUtilities);

Note that the definitions of the function bodies do not need this fix.

Turn off the Quick Math library

The documentation describes a Quick Math library of fixed point routines, but it doesn't seem to be included with the Windows version of the SDK (please let me know if I'm wrong and it's hidden somewhere). I inserted a #define qUsesQuickMath 0 statement in the 3DCotype_bcb.h file which disables use of the Quick Math library and uses the built-in floating point math instead.


valshdr.zip (23 KB zip file)

Contains the following files:

The above files will create the file valshdr.rdx, which you should move to the Ext folder of your Ray Dream directory (or one of its subfolders). The extension is a shader that provides the same functionality as the 'Value' shader (i.e. sets a value between 0 and 100). Not too exciting, I know, but at least it works.

You will need to modify the makefile so that the include (-I) and library (-L) paths point to the appropriate directories on your system.

Completed extensions

Current Projects

Small blue square

Back up to the Raydream page.
Back up to the C++ Builder page.

[Home] [Comp] [SF] [Med/Bio] [Other Sci] [Personal]

Small blue square
Updated 2001-9-9. Comments to webmaster@ultradrive.com
Copyright © 1998-2001 Evelio Perez-Albuerne. All rights reserved.
Valid HTML 4.01! Valid CSS!