# BMRT2.6 Windows Installation Notes

# December 13, 2000

Installing BMRT

If you have an older version of BMRT installed on your machine, remove (or move to a safe place) the old directory and all its contents before installing the new version.

Unpack the BMRT Distribution

Choose a directory into which BMRT will be installed (e.g. “c:\BMRT2.6”), and extract the contents of the BMRT2.6 zip file into it.

Set BMRT Environment Variables

### If you use Windows NT/2000/ME: edit your environment

Right click over the "My Computer" icon and select "Properties". Go to the "Advanced" tab and click the “Environment Variables” button. Add the bin directory of where you installed BMRT to your PATH variable, set the BMRTHOME variable to where you installed BMRT, and your SHADERS variable to the shaders directory of BMRT2.6. For example:

                   Variable: PATH

                   Value:[…];C:\BMRT2.6\bin

                   (i.e., add C:\BMRT2.6\bin to the end of the current PATH value.)

                   Variable: BMRTHOME

                   Value: C:\BMRT2.6\

                   Variable: SHADERS

                   Value: C:\BMRT2.6\shaders

If you had set these values during a previous installation of BMRT, make sure that any references to the old values are removed. The BMRTHOME environment variable should be “DOS-safe”. For example, if you install BMRT under
“c:\Program Files\BMRT”, you should set your BMRTHOME to something resembling “c:/Progra~1/BMRT”.

### If you use Windows 95/98: edit autoexec.bat

You must edit your autoexec.bat file to set the BMRTHOME and SHADERS environment variables, and to update your PATH to include the BMRT bin directory.

For example, if you installed BMRT on your C: disk at the top level, you could add the following to the bottom of your autoexec.bat file:

                   set PATH=%PATH%;C:\BMRT2.6\bin

                   set BMRTHOME=C:\BMRT2.6\

                   set SHADERS=C:\BMRT2.6\shaders

If you had set these values during a previous installation of BMRT, make sure that any references to the old values are removed. The BMRTHOME environment variable should be “DOS-safe”. For example, if you install BMRT under
“c:\Program Files\BMRT”, you should set your BMRTHOME to something resembling “c:/Progra~1/BMRT”.

Cygwin Compatibility

If and only if you have the cygwin package installed on your machine, remove the file “cygwin1.dll” from BMRT’s “bin” directory. If you are not sure if you have cygwin installed, move on to the next section, Testing BMRT. If you encounter problems while testing, see the Troubleshooting section.

# Testing BMRT

After unpacking the distribution onto your machine (let's say you put it in `C:\BMRT2.6` for this discussion) and making sure the rest of your setup is correct (see above), it’s time to test your setup as outlined below.

If you encounter difficulties, double-check that your various environment variables are set correctly, or see the Troubleshooting section below.

Open a MSDOS/Command window (a.k.a. "Command Prompt" under "Programs" in the Start Menu).
Change directories to the examples directory (you type the part in bold):

    C:\> cd BMRT2.6\examples

    C:\BMRT2.6\examples\>

### Test rgl

First, run rgl, the OpenGL-based RIB previewer on some rib files (you type the part in bold):

    C:\BMRT2.6\examples\> c:\BMRT2.6\bin\rgl teapots.rib

hit the esc key or q to close the window after it finishes rendering.

    C:\BMRT2.6\examples\> c:\BMRT2.6\bin\rgl limbo.rib

### Test slc

Next, compile some shaders (you type the part in bold):

    C:\BMRT2.6\shaders\> c:\BMRT2.6\bin\slc funkyglass.sl

    C:\BMRT2.6\shaders\> c:\BMRT2.6\bin\slc screen_aa.sl

    C:\BMRT2.6\shaders\> c:\BMRT2.6\bin\slc screen.sl

### Test rendrib

Next, render a scene using the hybrid raytracer/radiosity renderer (you type the part in bold):

    C:\BMRT2.6\examples\> c:\BMRT2.6\bin\rendrib -d 16 shadtest.rib

The `-d` option to rendrib will display the results directly to the screen. When the renderer finishes, you can press the w key while over the window to write out a TIFF file (the esc key or q will quit and close the window).

Test iv

Finally, render an image and display it using the iv.

    C:\BMRT2.6\examples\> c:\BMRT2.6\bin\rendrib shadtest.rib

    C:\BMRT2.6\examples\> c:\BMRT2.6\bin\iv balls1.tif

If everything worked okay, you're all set!

The `-d` option to rendrib will display the results directly to the screen. When the renderer finishes, you can press the w key while over the window to write out a TIFF file (the esc key or q will quit and close the window).

# Issues specific to the Win32 port

### Unsupported Features

Procedurals are currently unsupported in rgl. This shortcoming will be addressed in a future release.

### Filename and pathname conventions

In order to preserve cross-platform compatibility of RIB files, we strongly urge you to specify files and pathnames in RIB files (such as in "searchpath" options, ReadArchive calls, texture filenames, etc.) using the convention of forward slashes (“/”), rather than the backslash (“\”) to indicate directory hierarchy, and colons (“:”) rather than semi-colons to separate items in a searchpath.

If you must use backslashes to indicate directory hierarchies remember that, just like in C source code, a single backslash modifies the next character (i.e., \t is a tab, \n is a newline, etc.), so you must use two backslashes (“\\”) to indicate a single backslash in a path.

### Compiling Shadeop DLLs and Procedurals, etc.

In order to compile shadeop DSOs and procedurals for use with rendrib, you must link your DLL against the rendrib import library, rendrib.lib, found in BMRT’s “lib” directory.

A VisualC++ version of the client library, libribout, is shipped with BMRT 2.6. See examples/colorspheres.c for an example of a C program that uses it.

Note that BMRT is compiled using Microsoft’s Visual C++ (MSVC), and as such any Shadeop of Procedural DLLs to be used with BMRT must also be compiled with MSVC.

Compiling Shaders to DLLs

The shading language compiler, slc, can compile shaders to native DLLs by specifying the –dll flag at compile time. Shaders compiled this way can be significantly faster than the interpreted shaders that result when the –dll flag is not specified.

The –dll flag to slc assumes that you have Visual C++ installed on your computer, and that the path to the compiler (cl.exe) and linker (link.exe) is included in your PATH environment variable.

### Other Issues

Please note that many Windows built-in TIFF viewers can't read TIFF files that have an alpha channel, so any RIB files that have their last argument to Display as "rgba" (as opposed to "rgb") won't be able to be display these images. The iv image viewer included with BMRT handles these TIFF files correctly.

Troubleshooting

Shading Language Compiler

The shader compiler (slc), makes use of cpp (the C PreProcessor) and cygwin1.dll in the directory $BMRTHOME/bin (i.e., in the “bin” subdirectory under the place where BMRT is installed, which should be pointed to by the environment variable BMRTHOME). The versions of these files included in BMRT2.6 are from the fine folks at www.cygnus.com.

If you have difficulty compiling the examples shaders:

· Be sure your PATH environment variable includes the BMRT bin directory (e.g. “c:\BMRT2.6\bin”).

· Errors indicating multiple versions of “cygwin1.dll” while running slc:
c:\cygwin\tmp\BMRT2.6\bin\cpp.exe: *** Shared region version mismatch. Version 1A != 1E.
Are you using multiple versions of cygwin1.dll?

imply that you have an incompatible version of cygwin installed on your machine. If this is the case, simply remove the file “cygwin1.dll” from BMRT’s bin directory.

· If you have a C development environment installed, such as Borland's, slc might be using the cpp.exe that comes with that environment, rather than the version shipped with BMRT. Unfortunately, the output of Borland's cpp.exe seems non-standard, so slc can't use it. If you run slc and see:

            slc Error: (line 1) parse error

            No Code generated

This probably indicates that slc is using the incorrect version of cpp. You might want to change your path right before you compile shaders to only point to BMRT's bin directory.

· If, upon running slc, you see errors similar to:
'c:/Documents' is not recognized as an internal or external command, operable program or batch file.

Your BMRTHOME environment variable most likely is not “DOS-safe” and contains, e.g. spacs. Make sure that your BMRTHOME environment variable does not contain any spaces or other “DOS-unsafe” characters.

· If you encounter problems using the –dll or –dso flag to slc, with errors similar to:
'cl' is not recognized as an internal or external command, operable program or batch file.
make sure that Visual C++ is installed on your computer, and that your PATH is set to include the directories that contain the compiler (cl.exe) and linker (link.exe).

· If you're running under Win95/98, make sure that Norton Antivirus is not interfering with slc by disabling it temporarily.

### OpenGL

In order to use the OpenGL-based preview renderer, rgl, the iv image viewer, or view the output of rendrib directly to your framebuffer (by choosing the “framebuffer” output type, or using the “-d” flag on the command line), BMRT requires that OpenGL be installed on your system.

If you're running Windows 2000/ME, WinNT 3.51 or greater, or Windows 95/98, Microsoft’s OpenGL (OpenGL32.DLL and GLU32.DLL) should already be installed on your system. If they are not, Microsoft makes OpenGL available at ftp://ftp.microsoft.com/softlib/mslfiles/OPENGL95.EXE.

Finally, if you have a 3D accelerator; check with your board and chip manufacturers to ensure that you have the latest OpenGL drivers customized for your graphics accelerator, if any.

# Additional resources

The obvious place to start, after reading the included documentation, is the BMRT home page.

The USENET group comp.graphics.rendering.renderman is an invaluable source of information on BMRT and related topics.

Animal Logic provides a free version of MaxMan, their highly-regarded renderer interface to 3DS MAX, for use with BMRT.

Johan Aberg has written a set of notes/tutorials on integrating BMRT with Rhino.

Exluna, BMRT, and Blue Moon Rendering Tools are trademarks or registered trademarks of Exluna, Inc. in the United States and/or other territories. All other trademarks are the property of their respective owners.