[Bsod-mentors] Summer of Documentation - Proposal

[Tim Wakeham]

Skipped content of type multipart/alternative-------------- next part --------------
If there are images in this attachment, they will not be displayed.  Download the original attachment
Page 1
slcEditor, a RenderMan Shaders Parameters Tool
for Windows
Alexei Puzikov (http://www.dream.com.ua)
2000-06-10

Page 2
Contents
1 Prelude
2
1.1 What is slcEditor? . . . . . . . . . . . . . . . . . . . . . . . .
2
1.2 How to install slcEditor . . . . . . . . . . . . . . . . . . . . .
2
1.3 Contents of the distribution . . . . . . . . . . . . . . . . . . .
2
1.4 Copyrights and trademarks. . . . . . . . . . . . . . . . . . . .
3
1.5 Licensing Arrangement. . . . . . . . . . . . . . . . . . . . . .
4
1.6 Tech notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2 Quick introduction
6
3 FAQ
8
4 Tips and Tricks
10
5 Known issues and limitations
11
6 History of slcEditor
12
1

Page 3
1 Prelude
This is an early beta release of the slcEditor documentation. Since I’m not
a native English speaker errors might occure within the text, so any correc-
tions and suggestions are absolutely welcome.
The source code and distributives of this document can be found at http://www.dream.com.ua
along with distributives of slcEditor itself.
1.1 What is slcEditor?
The slcEditor application was started when I found myself spending 90% of
new image development time digging in the shaders attributes then reren-
dering again and again. Somebody might say this is because I’m new in the
BMRT and Renderman, but I hope even the pros will find the solution born
useful in their everyday work.
Briefly, slcEditor is an application which provides GUI for adjusting the
BMRT compiled shaders parameters. You can load the shaders, tweak their
parameters and preview the results.
If you’re not familiar with the terms I used above, consider visiting the BM-
RT web page and reading the good Renderman book, such as Renderman
Companion or ”Advanced Renderman: Creating CGI for motion pictures”.
This might help ;-)
1.2 How to install slcEditor
Just unzip the file you dowloaded to any directory. If you want to add the
Explorer icon dependencies for slcEditor to start after clicking on RMT file,
you’ll also need to manually edit the rmt install.reg file (change the paths
according to your environment) then double-click on that REG file.
There is no automatic installation or uninstallation procedure yet, thought
I’m planning to create one.
1.3 Contents of the distribution
1. doc/ - contains the online documentation for slcEditor in plain HTML
format (you’re reading now).
2. source/ - contains source code for several slcEditor parts:
(a) viewtiff - full Delphi source code for Viewtiff application
(b) hsv - Delphi source code for Color Chooser used in slcEditor
2

Page 4
3. applyrmt.exe - use this application to apply the RMT materials to
your RIBs
4. SlcArgWrap.dll - shared library, wrapper for libslcargs.lib supplied
with BMRT
5. teapot.rib - sample custom preview RIB file
6. viewtiff.exe - very simple applet for viewing the TIFF files. Full
source code is also available.
7. slander.exe - sLander application by Ian Stephenson
8. slander.txt - and it’s accompanying description
9. template.rib - sample template preview RIB file
10. rmt install.reg - installation Windows registry patch.
11. slced.exe - main slcEditor executable.
12. compiler.exe - wrapper for running slc.exe with output redirected.
1.4 Copyrights and trademarks.
Main idea, concept and programming: Alexei Puzikov, http://www.dream.com.ua
sLander idea, NT conversion and assistance: Ian Stephenson, http://www.dctsystems.freeserve.co.uk
slcEditor documentation: Richard DuPertuis
slcargswrap.dll: Sergei Migdalsky
Color chooser implementation, HSV conversion code: Earl F. Glynn, http://www.efg2.com/lab
GraphicEx library: c Copyright 1999, Dipl. Ing. Mike Lischke (public at lischke-
online.de)
Beta testing: Nick Gabchenko, Ian Stephenson, Richard DuPertuis
Idea and portions code used: TkMatMan by Andreas Butz, http://www.dfki.uni-
sb.de/∼butz/tkmatman/index.html
Icon artwork: Valera Poboiko
Scanf Pascal implementation by E. Sorokin
DFSMRUList, DFSEllipsisPanel: c 1999, Brad Stowers, All Rights Reserved,
http://www.delphifreestuff.com/
Bitmap resampler: c 1997,98 by Anders Melander
uucode:Copyright c 1996 by Artem A. Berman
The Blue Moon Rendering Tools (BMRT), including the programs rendrib,
rendribv, rgl, slc, and slctell, the libraries libribout.a, libslcargs.a, and all
3

Page 5
the documentation in this package are:
Copyright 1990-1997 by Larry I. Gritz. All Rights Reserved.
The RenderMan (R) Interface Procedures and RIB Protocol are
Copyright 1988, 1989, Pixar. All rights reserved.
RenderMan (R) is a registered trademark of Pixar.
1.5 Licensing Arrangement.
sclEditor is c Copyright 1999-2000 by Alexei Puzikov. All Rights Reserved.
http://www.dream.com.ua
This work (including software, documents, or other related items) is being
provided by the copyright holders under the following license. By obtaining,
using and/or copying this work, you (the licensee) agree that you have read,
understood, and will comply with the following terms and conditions:
Permission to use, copy, and modify this software and its documentation,
with or without modification, for any purpose and without fee or royalty is
hereby granted.
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED ”AS IS,”
AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WAR-
RANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE
OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIREC-
T, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in adver-
tising or publicity pertaining to the software without specific, written prior
permission. Title to copyright in this software and any associated documen-
tation will at all times remain with copyright holders.
1.6 Tech notes.
For those who cares ;-)
4

Page 6
1. As of version 0.6.0.1 slcEditor is 36043 lines of code, 100K of them is
main application source code.
2. slcEditor and most of accompanying applications are created Delphi 4
and lots of 3rd party freeware components (see c section for details).
Several pieces created and compiled with Visual C++.
3. Documentation for slcEditor is created in plain HTML format then
converted to TeX and ready-to-go HTML using custom-writen Perl
scripts. I’m using Valhalla Labs TeX distribution (fpTeX/web2c 7.3)
and Ghostscript 5.50 for producing the printable version of documen-
tation.
5

Page 7
2 Quick introduction
slcEditor is an application that allows BMRT users to tweak RenderMan
shader parameters interactively. It loads a compiled SLC file, provides a
GUI of all shader values that can be edited, previews the image, and exports
the RIB code. The user-created material can then be saved as a RenderMan
RMT material file, leaving the original shader intact.
Operating slcEditor is highly intuitive. The user points the program to
a shader directory. A click on a shader name reveals a field containing
the name of current shader and a click in that field will open a menu of all
shaders in the current directory. Separate selections are available for Surface
shaders, Displacement shaders, Light shaders or Other shaders (background,
depthcue, smoke, etc.), all of which are sorted automatically when a direc-
tory is opened.
Once a shader is loaded, the parameter buttons appear. Next to each is
a value the user can change. A click on a numerical value will bring up a
spinner that will allow adjustment the value by increments of 0.1. Clicking
on a color value presents a button which will launch a color picker. Alter-
nately, the user can type precise values directly into a field. A right click on
any of the parameter fields pops up a menu that allows the user to revert a
value back to the shader default. Also accessible from this menu is an editor
for rewriting the SLC file’s source SL file.
To see how the new parameters look, the user clicks the preview window. A
full-color rendering will appear. The preview can appear as a sphere, cone,
cylinder, cube, patch or even a custom object. The preview itself allows ad-
justments for size, light brightness, pixel samples, shading rate, gamma and
includes a field where custom command line options can be typed. slcEditor
offers a choice of render previews, using BMRT’s rendrib and the experi-
mental sLander.
When the preview looks good, the user looks to the Generate RIB code
button. Next to it are check boxes allowing inclusion of Declare statements
and/or colors, and whether or not to export directly to the clipboard. When
the button is clicked the code appears in the field below. Any part of it can
be copied and pasted into a developing RIB file. A button is also provided
for the user to drag and drop the code into any OLE-compliant text editor.
If a RIB was written by an application that produced the string: Attribute
”identifier” ”name” ”xyz”, or if the user has entered these calls manually,
sclEditor’s Applyrmt can be used. Entering the path and file name in the
In file field creates a button for each attribute indented in the file. Next
6

Page 8
to this is a blank field. Double clicking here will open a requester for the
path to the materials directory. A material can be chosen for an attribute
or the field can be left blank, which will leave the material for that attribute
unchanged. Clicking the Apply button assigns the materials in a new RIB
file named in the Out file field.
slcEditor saves work as RenderMan RMT files. When it loads an RMT
it automatically restores the state of the application and the interface looks
exactly the same as when the user last saw it. Editing can then be resumed,
BUT SAVING A MATERIAL CAN OVERWRITE THE ORIGINAL RMT
SO BE CAREFUL. sclEditor comes with a browser which views thumbnails
of saved materials. Files can be loaded directly from the browser or from
the GUI file menu.
7

Page 9
3 FAQ
Q: How to configure slcEditor to render previews with renderers
other then rendrib?
A: First of all, you should be aware you have the shaders compiled for
the renderer you’re going to use. For example, you’re adjusting the BMRT
shader (SLC) but to render the preview with Aqsys you should also have
the same shader compiled to SLX file. Note only BMRT compiled shaders
(*.SLC) are supported for loading into slcEditor.
Next, you should add several lines to slced.ini manually:
[renderers] r1=aqsys::cribber %s r2=angel::angel %s or something else. Sim-
ply, you.re adding another clause into your INI file that containc several
items, each of format below:
r#=[displayed name]::[path+exename + optional parameters] %s
Next time you’ll start slcEditor new options will appear in preview type
selector.
Q: Why does it take so long for slcEditor to start sometimes?
A: When slcEditor opens it scans the current directory and sorts the shaders.
Depending on how many shaders are in the directory, this can take a while.
One workaround is to categorize your shaders in subdirectories according to
type or project their belongs to. Keep a few in a basic directory and make
that the default. This will speed things up considerably.
Q: Shaders in BMRT and Renderman are written with *.sl, *.slo
and related extensions. slcEditor output is *.rmt, so how to use
it with BMRT and RMan?
A: A little bit of theory first.
One should distinguish the shader source code and the compiled shader.
Shader source code is *.sl; compiled shaders are different for each renderer;
for example, prman are *.slo and BMRT are *.slc.
Now on the subject.
slcEditor is working with compiled shaders from BMRT and arranges them
into the proprietary material format - RMT (Renderman Material). This
is an ASCII text file that consists of compiled shader names (without their
paths), parameters and their changed values, direct RIB Surface/Displacement/etc
calls for those who’d like to load the RIB code from that file and rendered
material previews encoded with standard UUencoding. So the RMT file is
just a proprietary technology for storing the results of tweaking shaders in
8

Page 10
slcEditor.
Thus one can reuse the RMT files in several ways. First, you can use your
target RIB file as the template together with slcEditor. Next, you can use
the applyRMT application to assign the RMT files to the objects within the
RIB file (proved to be useful with Rhinoceros and Maya exported RIBs).
Last, you can just simply cut and paste the RIB code from RMT file to your
RIB file
Q: Is it possible to control reflection/refraction materials through
slcEditor?
A: Yes and no. Under BMRT reflection and refraction are the core fea-
tures of the renderer and shaders can implement that features; thus you can
adjust the corresponding shaders to achieve effect needed. Under prman
additional steps needed to get the reflection/refraction effects; that steps
are not covered by slcEditor functionality.
Q: Are PRMan shaders 100% compatibile with BMRT’s?
A: With several small exceptions, you can recompile the source code un-
der both systems without any problem. However, the visible results will
vary. Note the prman is not the raytracer but raycaster; BMRT is raytracer
and have the radiocity option. Thus if the shader is employing the raytrac-
ing option used in BMRT it will not work with prman and vise versa. For
details on difference between prman and BMRT consult the BMRT docu-
mentation and www.renderman.org web site.
Q: In slcEditor I can only see BMRT shaders without access to
PRMan’s, why?
A: To be able to work with prman shaders I need to compile the corre-
sponding library. To compile it I need to buy the prman. It costs several
thousand dollars.
Q: What order are the shaders brought up in the lists? Is it just
by the order they’re in in the folder?
A: Yes, they put in the directory listing order but keep in mind that I’m
scanning two directories each time - the one set in SHADERS environment
variable and the current one you’re using. That way the shaders from the
current directory pop in the list then the standard shaders are listed.
Inside that two subsets the list seems to be alphabetical on my computer.
9

Page 11
4 Tips and Tricks
Here you’ll find several tips and tricks. You can consider it a help file until
the real documentation will be created. Also I’m looking forward for new
tips and trick to be included here.
1. You can launch the preview by clicking on it.
2. Most of the statistics and error messages are displayed in the status
bar, so if you think something is wrong just take a look there. It might
contains an error message ;-)
3. slcEditor is about SLC files, not SL. So if you’ve changed something
in your SL source code, don’t forget to recompile it before previewing.
4. True displacement preview rendering might take a lot of memory and
time.
5. If you turn off the console window, there is no way to see the rendering
statistics or error messages. Use this option only if you’re sure there
will not be mistakes or renderer faults while making the preview.
6. slcEditor places all the temporary files into the directory which is
assigned to Windows TEMP environment variable (the default one is
WINDOWS\TEMP or WINNT\TEMP). But if you’re selecting the
”No preview” option, using the custom RIB file ot RIB template for
preview, the RIB code will be generated in the same directory from
which you are previewing shaders (your current directory).
7. To refresh the shaders lists, use the ”Change Directory” command
without really changing one. Just press OK.
8. Hint: double-clicking in numeric field will repeat the last operation
done with such field using the up/down spinner. This applies to shader
parameters only.
10

Page 12
5 Known issues and limitations
1. sLander version 0.51 is included along with this release of slcEditor.
Thanks to Ian Stephenson for his great tool and permission. sLander
is an experimental software. All questions regarding it behaviour,
possible bugs and improvements should be sent to Ian directly. Please
also register your copy by droping the message to Ian.
2. sLander known to not support several shader variables. Also the Vol-
ume shaders are not tested well under sLander. Refer to sLander
documentation for details.
3. If the material file will be reviewed by another application during the
Save operation, it’s contents will not be overwriten but added. This is
a known behaviour of used tools, not bug. To prevent misunderstand-
ing please don’t alter the materials files with other applications while
saving into them with slcEditor.
4. Preview settings and options are supplied to the RIB code as is, with-
out verifying. This might result in incorrect RIB code or failure during
the renderer calls. If you’ll have such mistakes during the preview ren-
dering, please verify your RIB code first (it can be found either in your
current directory or in standard Windows TEMP directory).
5. This software supports BMRT compiled shader files only (*.SLC). Any
shaders from BMRT version 2.5 and higher will work. This software
has no support for either Pixar’s prman for NT or shader source code
(*.SL).
6. sLander application now supports two preview types only: sphere and
patch. The patch preview is the standard, thus anything but sphere
will be rendered as patch.
7. The custom RIB object edit box is disabled, you can’t edit it directly.
This value can be changed using the details button near the edit box.
8. The application is scanning it’s current directory for SLC files while
starting. Thus if you have lots of compiled shaders in the slcEditor
startup directory, this might made the startup time longer. Also if
you’ll change the directory to one with lots of SLC files, the operation
might take some time. I’m working on optimising the scanner code.
9. This software lacks of documentation. I’m not a native English speaker
so I think this might be better if the person with some technical writer’s
skills ( or just somebody with good English ;-) ) will help me with
creating the good documentation. Please contact me if you think you
might help here.
11

Page 13
6 History of slcEditor
June 10, 2000
slcEditor 0.7.0.0 is out.
Changes since 0.6.0.1
1. Light shaders support.
2. slander now starting OK if working in another directory.
3. Significal code cleanup; preparations for Open Source release.
4. Documented feature: external renderers support; consult FAQ section
in documentation.
March 27, 2000
slcEditor 0.6.0.1 is out.
Changes since 0.6.0.0
1. Now the file mask for textures is *.TIF*,*.TEX and *.TX
2. Exception handlers added to most of dangerous cases.
3. Scrollers save their real settings (one pixel bug fixed).
4. Preview size now visible again.
5. Bug fixed: Rhino RIB files now works as template files as is. Previously
they were rejected because were saved using Unix scheme (not CR+LF
at the end of line but LF only).
6. Templates now scanned for their real Display filenames. So you’ll be
able to see results loaded into slcEditor preview window even if your
display target not equal tempfile.tif.
7. applyRMT remembers it’s last directories and files.
8. You can start rendering automatically in applyRMT.
March 18, 2000
slcEditor 0.6 is out.
Changes since 0.5.0.0
1. BMRT 2.5 compatibility; new slcargwrap.dll added. Lots of code
changes because of rendrib/slc programming interface changes.
2. New look and feel; main toolbar implemented (suggestions welcome).
12

Page 14
3. TIFFER.DLL changed to Delphi native code library, GraphicEx. Due
to this some incompatibilities might happened during the beta period.
4. New splitters working again.
5. Shader source editor highlights the whole SL keywords set (thanks to
c.g.r.r. publication).
6. Fixed bug with slander preview: the displacement shaders are visible,
too.
7. SLC compiler status visible in the sl editor window. More features
later.
8. Shaders from the current directory placed first in the list.
9. sl editor have the search function a la MSVC IDE (I think...)
10. Probably bug fix: the application changes the directory when loading
the material from that directory.
11. All the windows saves their positions.
12. You can press ESC, Enter in Browser; Enter in find text field.
13. You can double-click on the error number in sl editor to scroll to that
error. Warning: this works on Win9x only.
January 15, 2000
slcEditor 0.5 is out.
Changes since 0.4.0.1
1. Misc interface changes. Interface now more consistent in all parts of
slcEditor. Most of the menu commands now have shortcuts.
2. Documentation initial release. Help menu commands now binded to
actual HTML files. Note the documentation described previous ver-
sion, 0.4.0.1. This should be changed soon.
3. Shader parameters’ grids now have the right mouse button menu.
4. Surface and opacity color editors can be launched by clicking on their
color previews.
5. Bug fixed : in color chooser any color now can be saved to the stack
(previously colors with R=0 were saved but were not drawn correctly).
6. Full set of declares can be generated now. It might be a good idea to
turn this option off before saving the material.
13

Page 15
7. Progress dialog added for displaying the directory scanning process.
8. Color parameters are now visible in the editing grids.
9. Several minor fixes in code.
10. Generated RIB code now can be dragged to the text editors using
special handler (tested with MS Word).
11. You can supply custom rendrib command line options to be used while
rendering the material previews (something like ’-radio 12’).
12. You can use the RIB templates for previewing the materials. Create
the ordinary RIB file, put the
#insertmaterialhere
line in the place you’d like your material to be placed. Then the
preview will generate the RIB code, put it to the temporary file, gen-
erated using the template (#insertmaterialhere line will be replaced
with your actual shaders calls), then start the ordinary preview pro-
cess.
13. Two REG files has been merged. The icon DLL has been removed
from the installation.
14. Final one. I’m looking for the people to optimize the current color
chooser. In the current state it’s pretty good but unusable sometimes
(for example, you can’t drag the color bars interactively). I’m planning
to giveaway the slcEditor source code, so the color chooser part will
be the first piece to become free ;-)
15. Bug fixes: layout now can be saved in the INI file.
October 28, 1999
slcEditor 0.4.0.1 is out.
Changes since 0.4.0.0
1. Bug fixed. slcEditor now works on Windows systems with non-US
regional settings. The decimal separator symbol is now . on all ma-
chines.
2. sLander 0.4 included with this release.
October 5, 1999
slcEditor 0.4.0.0 is out.
Changes since 0.3.0.0
14

Page 16
1. The SL file editor added (very simple thought). More features in sl
editor in the next versions.
2. This version also includes the (very) simple TIFF files viewing appli-
cation viewtiff. Also the viewtiff source code is included.
October 2, 1999
slcEditor 0.3.0.0 is out.
Changes since 0.2.0.2
1. Numeric shader parameters now have their own spin editors. Thus
you don’t need to edit them directly. Note the increment defaults to
0.1 in the current version.
Hint: double-clicking in numeric field will repeat the last operation.
2. applyRMT - left column is now fixed. This might prevent you from
typing in the wrong area.
3. applyRMT - bug fixed. If you change the order of attribute names
within the source RIB file, in the previous version the scheme were
loaded incorrect (the materials were assigned to the positions, not the
names themselves). Now everything is correct.
4. Now slcEditor can be launched with optional parameter, the RMT file
name, like so:
slced.exe c:\materials\glass.rmt (note the full path in the material
filename).
This way the RMT file will be loaded on startup. The Win95 and
WinNT REG files and icon DLL are attached to this release to simplify
the Explorer assignment of RMT files to the slcEditor application (if
you’ll double-click the RMT file in Explorer, the slcEditor will be
started). (Both REG files are about identical, but NT seems to cache
the icon...)
5. BUG fixed - slcEditor now saves settings only to the directory in which
it resides, not to the last directory when the material was loaded.
September 22, 1999
slcEditor 0.2.0.2 is out.
Changes since 0.2.0.1
1. Filenames in material browser now ellipsified (i.e. if the filename is
too long to fit in the cell, it will be shortened to the ”filena...” form).
15

Page 17
2. applyRMT is now much more functional application. You can save
the state of this application (called ”scheme”) so you don’t need to
resetup the material applying rules again after restart. Just load the
scheme.
September 18, 1999
slcEditor 0.2.0.1 is out.
Changes since 0.2.0.0 (This is mostly a bug fix release).
1. BUG - misc shaders were not loaded correctly - fixed.
2. BUG - changed shader parameters were not saved correctly - fixed.
3. applyRMT now the part of the slcEditor distribution.
(a) Export your RIB geometry from Rhino, Maya or any other pack-
age that allows the attribute to have names (like this: Attribute
”identifier” ”name” ”xyz”). You can place such calls within your
RIB files manually.
(b) Prepare your materials using slcEditor.
(c) Start applyRMT. Load the source RIB file. Select destination
RIB file and other options.
(d) For each attribute name choose the material you’d like to apply
to it. You can leave the material field empty.
(e) Click apply button.
(f) Render the destination RIB file.
September 17, 1999
slcEditor 0.2.0.0 is out.
Changes since 0.1.0.0 (in no particular order)
1. True displacement displacementbound line now inserted in temporary
RIB files.
2. Thumbnails are now stored within the material files (RMT) using the
UUE encoding. Please note that the previews are stored into the mate-
rial files next time you save them, not automatically after rerendering.
Also due to the technique used, only previews with size of power two
(64, 96, 128) will create thumbs of good quality (Hermite filter for
those who cares).
3. Actual shader RIB calls are saved within the RMT material files (for
future and 3rd party needs). Now if you want your utility to support
the RTM material format, you don’t need to parse the full file, only
the actual RIB call lines.
16

Page 18
4. File-Browse command launches the Materials Browser. Note that this
is an experimental feature and scanning the directory with lots of
materials might take a time.
5. BUG - rmm (instead of rmt) default extension in Open Material dialog
- fixed.
6. Directories history implemented and stored between sessions. Now
you can choose directories from the list in Materials Browser.
7. Libslcargs interface implemented. slcEditor no longer parses the SLC
files directly but uses standard slc.h and libslcargs.lib calls. Unfortu-
nately, libslcargs is not as fast as parsing SLC files directly...
8. Warning! slcEditor now does not support the shader names with more
then one point, i.e. fur.shader.slc.
September 4, 1999
slcEditor 0.1.0.0 is out.
17