============================================================================== POVShell Version 2.3 The Development Environment to POV-Ray by Andreas Peetz [100101,1670] ============================================================================== Contents: 1. Introduction 2. Installation/Quick start 3. Dialog elements 4. Menus, Commands and Hot keys 5. Editor keys 6. Option Quick keys 7. Distribution policy/Legal information 8. Thanks A. Special files and file formats B. Using the Template feature C. Warnings and errors D. Command line parameters E. Contacting the author 1. Introduction --------------- The 'Persistence of Vision Ray Tracer' (POV-Ray) is nowadays the most sophisticated and best known non-commercial raytracing-program. Its original authors, David Buck and Aaron Collins, and all the members of the POV-Ray team have done (and are still doing) a pretty good job on that program. I'd like to thank these guys for the many hours of pleasure that I'm having with POV-Ray and the brilliant pictures produced by it! This description of the POVSHELL-program assumes that you are familiar with using POV-Ray or at least own a version of the POV-Ray-program. The actual version of PovRay is 2.2. PovShell will also work with earlier versions and even with the original DKB-Raytracer. POV-Ray is designed to be a 'command-line-program', this means that you have to supply all of its parameters on the command-line when calling the program. This is fine for batch-processing, however, if you are writing your own POV-Ray-scene-scripts, you have to run the program repeatedly for quick preview-traces in order to test your scripts and different parameter settings. You will soon get tired of typing the same command-line over and over. To become rid of that I wrote POVSHELL, a user-friendly easy-to-use interface to POV-Ray. With POVSHELL you can a) load and edit one or more POV-files, b) set all raytrace-parameters via pulldown-menus and option-windows c) and finally call POV-Ray to trace the scene-file you are currently editing with the parameters you have set. POVSHELL was developed using the Turbo Vision-features of Turbo Pascal 6.0. Turbo Pascal and Turbo Vision are registered trademarks of Borland International, Inc. 2. Quick Start -------------- 2.1 Installation The following files have to be copied to a directory of your choice (e.g. the direcory of the POV-Ray-program): POVSHELL.EXE (the executable) POVSHELL.OVR (overlay file) POVSHELL.HLP (the help file) POVSHELL.TPL (template definition file) That's all! Note: If you are upgrading from an earlier version of PovShell, you may replace the old POVSHELL.EXE-file. Version 2.3 is compatible to prior versions, i.e. you can continue to use your DEF-files. If you are upgrading from version 2.0 read App.B in order to use the new template feature! 2.2 Running the program for the first time Note: Since version 2.0 context-sensitive help is available everywhere in PovShell. Just press F1! For information on how to use the Help system press F1 twice. Start POVSHELL.EXE from the DOS-prompt. If this is the very first time you are running POVSHELL, a dialog box will pop up where you have to specify the default-POV-file-path, the default POV-Ray-output-path and the name of the POV-Ray-executable. This dialog-box can be activated later again via the Setup|Directories- menuitem (see. 4.5). The information you enter will be saved in a file and loaded whenever you run POVSHELL again. Close the box by pressing ENTER or clicking the OK-button. You will then see a desktop-screen with a menu-line at the top and a status-line a the bottom. If you are familiar with the IDE of Turbo-Pascal or any other Turbo-Language, you will 'feel at home' at once. There are three ways to activate the menu-items: a. Hold down the ALT-Key and press the highlighted character of the item. Example: To open the 'File'-menu hold down ALT and F. b. Press the F10-Key. You can then select an entry of the Top-menu-line with the cursor-keys. Press RETURN to activate it. c. If you have a mouse and a mouse-driver loaded (you will then see the mouse-pointer on the screen), just move the mouse-pointer to the menu- item and click on it. Some commands can be activated by 'Hot keys', e.g. the File-open command can be activated by pressing F3. Some Hot keys are listed at the bottom-line. For now, press F3 to open a POV-file. A file selection box will appear. Walk through the directories and pick one of the POV-files. If you are confused now and don't know how to do this, refer to section 3 for further assisstance. Once you have opened a POV-file you will find it loaded into an editor- window, where you can work on it (or not). For a description of the editor- commands refer to section 5. Now use the 'Options'-menu-items to set the trace-parameters. Assuming that you are familiar with POV-Ray, you will certainly know the meaning of the options and selections that are listed in the various dialog boxes. Again further explanations can be found in section 4. To trace the picture select the 'Run'-menu-item or just hold down the Ctrl- key and press F9. If you have chosen to produce an output-file you will be asked to name the output-file and then POV-Ray will be called with the parameter-settings you have selected. After tracing you will be returned to the POVSHELL-interface. You may exit POVSHELL at any time by selecting 'Exit' from the 'File'-menu or by pressing ALT-X. 2.3 Monchrome monitor support People who want or have to use PovShell with a B&W-display should use the commandline-switch /b to start the program. Type POVSHELL /B at the DOS-prompt! 3. Dialog Elements ------------------ The dialog-boxes offered by POVSHELL generally consist of three types of elements: check-boxes, radio-buttons and input-lines. To switch between the elements of a dialog-box use the TAB-key. To close a dialog-box and confirm the changes made in it, press ENTER or click on the OK-button. To close a dialog-box without changes press ESCAPE or click on the Cancel-button. 3.1 Check-boxes [ ] [X] Check-boxes are used for turning on and off various tracing-options, e.g. anti-aliasing or the verbose-mode. If an option is turned off the check- box looks like this: [ ]. if it is turned on it looks like this: [X]. Toggle with the space bar or by clicking with the mouse! 3.2 Radio buttons ( ) () Radio-buttons are used to select one (and only one) item out of a list of items, e.g. to select the output-format (TGA, Dump or RAW). If an item is selected the radio-button looks like this (), otherwise like this: ( ). Walk through the list with the cursor-keys, select one item with SPACE! 3.3 Input-lines Wherever you have to enter a particular number (e.g. the output-file- buffersize) or a filename (e.g. the output-filename) you will be prompted for it in an input-line. Just type the values you want to use. If your input is incorrect or out of range it will be rejected! Note: If you are not sure what selections to use then refer to the Online-help to get a brief description of the options and the inputs' effects (Press F1 anywhere and anytime!) 4. Menus, Commands and Hot keys ------------------------------- 4.1 File menu - Open... : lets you select a POV-file that will be loaded into a new editor window - New: opens a new empty editor window - Save: the file you are currently editing will be saved - Save as...: the file you are currently editing can be saved under a name of your choice - DOS shell: opens a DOS shell. Return by typing EXIT at the DOS-prompt! - Exit: Leave program. If you have unsaved files open, you will be prompted to save them. 4.2 Edit menu - Undo: lets you undo the last change you made to the current editor window. - Cut: cuts the selected text out of the current editor window and places it in the clipboard. Select text by holding down SHIFT and moving the cursor or by moving the mouse with the left button pressed. - Copy: copies selected text to the clipboard. - Paste: inserts text from the clipboard to the current editor window - Show clipboard: shows the clipboard window. The clipboard is a special editor window which is used to exchange text-blocks between two 'normal' editor windows - Clear: clears the selected text from the current editor window. 4.3 Search menu - Find...: lets you find a string in the current editor window - Replace: lets you find and replace a string by another string - Search again: finds/replaces a string that was searched for again. 4.4 Window menu - Size/Move: resize and move an editor window on the desktop - Zoom: zoom/un-zoom an editor window - Tile: tile editor windows on the desktop - Cascade: cascade them - Next window: switches to next editor window - Previous window: switches to previous editor window - Close: closes the active editor window 4.5 Options menu - Output...: (ñF, ñC, ñB) lets you specify the output-format, continue flag and output -buffersize Note: In version 1.0 of PovShell you also had to specify the output-filename in this dialog-box. This has been changed. You will now be asked for the output-file-name each time you start a trace (see. 4.8 Run) - Display...: (ñD, +W, +H) for the specification of the display-adapter, image-width and image-height - Trace...: (+Q, ñA, ñJ, +R, ñMB, +MS, +MV) lets you specify the rendering-quality, anti-aliasing, anti-aliasing-jitter and -number of rays, the bounding slabs-option, symbol-table-size and version compatibility mode - Libraries...: (+L) These are the paths that are passed to POV-Ray via the +L option. Specify up to 10 paths, separated by ; - Misc...: (ñV, ñP, ñX, +K, +S(R), +SC, +E(R), +EC, other...) lets you toggle the verbose-, 'pause after trace'- and 'early exit'-flags, a clock value, and start/end-rows/columns of tracing. New in version 2.2: an inputline for additional options that are currently not supported by the original POV-Raytracer, but by various modified re-compilations of the program (e.g. FTPov by Dieter Bayer). - Save options...: lets you save the currently selected tracing parameters in a DEF-file. - Save Default options: saves options in the DEFAULT.DEF-file (see A.2) - Retrieve options...: lets you retrieve parameter settings that were saved before. 4.6 Setup menu - Directories...: 1. Default POV-file-path: this is the directory POVSHELL will change to when you choose to open a POV-file 2. Default-Output-path: this the directory where the output-files will be written to unless you do not change the directory when prompted for the output-file-name. Note: If you leave it blank, the default-output-path will be the directory of the POV-file you want to trace 3. Executable path: This is the path to the executable POV-Ray-program (normally POVRAY.EXE). Specify the full file name, e.g. C:\POV\POVRAY.EXE. - Editor...: 1. Create Backup files: if you choose this item, the editor will save a copy of each file you open using a BAK-extension 2. Insert-Mode: if selected the editor-cursor will be in insert-mode on startup. You can toggle this by pressing the Insert-Key or CTRL-V. 3. AutoIndent-Mode: if selected the editor will use the autoindent mode, i.e. each time you begin a new line the cursor will be placed in the column were the above line starts. Good for writing structured scripts. 4. Save Desktop on exit: if selected PovShell will save the names of all open files on program-exit. They will then be reopened automatically on the next startup (cf. A.5) 5. 43/50 lines: switches to a 43 lines display (on EGA) resp. to a 50 lines display on VGA. Default is 25 lines. 6. TabSize: the number of spaces PovShell uses to display a Tab-character. - Colors...: Lets you customize the PovShell colors (look at the online help for a detailed description of the dialog box!). This command will not be available if you tell PovShell to use the B&W-palette by using the commandline-switch /b ! 4.7 Templates menu In this menu you get a list of predefined PovRay-templates. If you select e.g. the Camera-item the following will be inserted in the current POV-file at the actual cursor position: camera { location < , , > look_at < , , > } For more information on how to use the template-feature refer to Appendix B. 4.8 Run Runs POV-Ray with the file you are currently editing and the actual parameters settings. If you have selected an output-format other than 'none' you will be asked to name the output-file before PovRay is launched. Default is: Default Output-file path from SETUP|DIRECTORIES... + the name of the POV-file you are tracing + an extension that is generated from the output-format 4.9 Help-menu - Introduction: a brief introduction to the program - PovShell Index: the complete list of PovShell commands - Help on Help: how to use the help system - Last Topic: pops up the previous shown help topic - PovRay reference: content page of the PovRay reference - About: about PovShell 4.10 Hot-Keys - F1: context sensitive help - Shift-F1: help index - Alt-F1: previous help topic - Ctrl-F1: PovRay reference - F2: save file - F3: open file - Alt-F3: close file - F5: zoom/unzoom editor window - Ctrl-F5: size/move window - F6: next window - Shift-F6: previous window - Ctrl-F9: run - F10: menu - Alt-X: Exit 5. Editor keys -------------- The Editor uses WordStar-compatible key-commands: 5.1 Cursor movement Ctrl-E: cursor up Ctrl-X: cursor down Ctrl-S: cursor left Ctrl-D: cursor right Ctrl-A: word left Ctrl-F: word right Ctrl-R: scroll page up Ctrl-C: scroll page down 5.1 Delete commands Ctrl-G: delete character under the cursor Ctrl-H: delete character left of the cursor Ctrl-T: delete word beginning at cursor position Ctrl-Y: delete actual line 5.2 Quick keys Ctrl-Q-A: Replace a text string Ctrl-Q-C: Go to the end of the text Ctrl-Q-D: Go to the end of the line Ctrl-Q-F: Find a string Ctrl-Q-H: Delete line up to cursor Ctrl-Q-R: Go to the top of the text Ctrl-Q-S: Go to line start Ctrl-Q-Y: Delete line beginning at cursor 5.3 Block keys Ctrl-K-B: Mark start of Textblock Ctrl-K-C: Paste block from Clipboard Ctrl-K-H: Toggle block-highlight Ctrl-K-K: Copy block to Clipboard Ctrl-K-Y: Cut block to Clipboard 5.4 Others Ctrl-L: Search again Ctrl-V: Toggle Insert mode Ctrl-M: New line (=RETURN) 6. Option Quick keys -------------------- Since version 2.0 there is a quick key access to all PovRay-options. You need not to use the Options...-menu if you remember the letter of the PovRay-option you want to change. Just press Ctrl-O and then this letter (e.g. Ctrl-O-V to change the verbose option). Then the appropiate dialog box will pop up and lets you make your changes. Ctrl-O-A: AntiAliasing Ctrl-O-B: Buffersize Ctrl-O-C: Continue Ctrl-O-D: Display-Adapter Ctrl-O-E: End-Row/-Column Ctrl-O-F: Outputformat Ctrl-O-H: ImageHeight Ctrl-O-J: AAJitter Ctrl-O-K: Clock-Value Ctrl-O-L: Library-paths Ctrl-O-M: Bounding slabs Ctrl-O-P: Pause when finished Ctrl-O-Q: Quality Ctrl-O-R: Number of AA-rays (to be squared) Ctrl-O-S: Start-Row/-Column Ctrl-O-V: Verbose Ctrl-O-W: Image Width Ctrl-O-X: Allow early exit 7. Distribution policy/Legal information ---------------------------------------- PovShell version 2.3 is FREEWARE. Explaining my understanding of the term FREEWARE this means: 1. This program may be used, copied and distributed by anyone if the following conditions are fulfilled: a) The distribution of PovShell must include ALL files that come with the program. None of the files may be modified in any way before distributing them. The easiest way to fulfil this condition is to distribute only the original archived version of the program as published by the author. b) PovShell itself may not be sold by anyone. However, it is legal to charge a minimal fee for the distribution of the program (including the costs for distribution media and shipping, resp. downloading). 2. PovShell must not be "bundled" with any other product without the explicit permission of the author, especially when there is a fee for that product. PovShell 2.3 includes a customized version of the file POVRAY.DOC which is provided as part of the POV-Ray package. For legal information on the distribution of the POV-Ray package please read the file POVLEGAL.DOC! 8. Thanks ---------- I want to thank all the people who helped me to improve POVShell since the first release in Dec.1993. Special thanks are going to Dan Farmer for a critical review of version 1.0 and to Webb Moore for his idea of adding the template-macro feature and supplying the pre-defined templates. Appendix A. Special files and file formats ------------------------------------------ A.1 POVSHELL.CFG POVSHELL will store the Default-POV-file-path, the output-path, the path to the executable, its editor settings, color informations and run-options in the file POVSHELL.CFG. DO NOT EDIT THIS FILE! Use the appropiate commands and menus in POVSHELL to change the parameters. POVSHELL.CFG will be stored in the directory where POVSHELL.EXE resides. It will be read by the program every time it is started and it will be written every time you exit it. A.2 DEFAULT.DEF On startup, POVSHELL will scan the directory where POVSHELL.EXE resides for a file named DEFAULT.DEF. If it is found the options stored in it will be loaded. There is no need to edit this file! If you want to save or change startup options, select the Options|Save default options-menuitem. A.3 DEF-File formats Note: a. If you have DEF-files written on your own you can load then into POVSHELL via the Options|Retrieve Options...-menuitem! You can also use the DEF-files that are distributed by the Pov-Team with the latest version 2.2 of the Pov-Raytracer. b. If you have saved options from POVSHELL via the Options|Save Options...- menuitem into a DEF-file you can also use these files outside POVSHELL by typing POVRAY +i +o at the DOS-prompt. c. If you save options only those parameter settings will be written into the DEF-file which are NOT the POV-Ray-DEFAULT settings! A.4 POVSHELL.TPL Since version 2.2 this file is used to store *all* the Template-definitions. You are encouraged to edit this file to meet your own requirements! File format: 1. Each template starts with a line containing a colon in the first column which is followed directly by the name of the template (and nothing else!) Example: :Light_Source ... The Template name will occur in PovShell's Template-selection-box. It is case-sensitive and limited to 12 characters. 2. All lines that start with a semicolon are ignored by PovShell. Those lines may be used to store template-related comments. They are only visible when editing POVSHELL.TPL. Don't mix these comments with the PovRay-comment-lines starting with // or embraced by /* ... */. PovRay-comments that are part of a template will be inserted by PovShell if you select that template! Example: ; This line will not be inserted. // This line will be inserted. 3. Any line that does not define a new template (s.1) and does not start with ; belongs to the template itself and will be inserted in the current editor if the appropiate template is chosen from the template- selection-box. A template definition ends where the next template starts or where the file POVSHELL.TPL ends. Note: If you are upgrading from version 2.0 and have written TPL-files on your own you have to manually convert these files to the new format! A.5 POVSHELL.DSK This is the PovShell-Desktop file. If you have chosen the 'Save Desktop on exit'-item in the Setup|Editor...-dialog-box all open files (i.e. their names) will be saved in the Desktop-file when you exit the program. On the next PovShell-startup the files listed in the Desktop-file will be automatically reopened. NEVER EDIT this file! A.6 POVSHELL.HLP This is the PovShell-helpfile. It includes all the help texts and binary coded information on indices and hyper-links. NEVER EDIT this file! PovShell will still work when the help file gets lost, but it *will* crash if it gets corrupted! A.7 Temporary files Every time you call 'Run' from the POVSHELL-menu the following will happen: 1. The contents of the active editor-window will be saved in a temporary file named $SHELL$.POV. 2. The actual parameter settings will be saved in a temporary file named $SHELL$.DEF. 3. POVRAY.EXE is called using the temporary files. 4. The temporary files are deleted. Normally the temporary files are stored in the PovShell-directory. However, if you have a DOS-environment-variable TEMP defined, the files will be written to the directory where TEMP is pointing to. If you want to use this feature place a command like SET TEMP=C:\TEMP in your AUTOEXEC.BAT and make sure that the specified directory exists! Appendix B. Using the Template feature -------------------------------------- The Template feature was designed to have quick access to PovRay command- templates and other text fragments that are often and repeatedly used. Imagine you are working on a scene file and want to insert a camera- command but you cant remember the correct and complete syntax of the command. Just click on the Template menu-item, a list of pre-defined templates pops up. There you can select the 'Camera'-entry, and the template will be inserted in your script at the current cursor position. The cursor stays where it is, you can now fill out the template. PovShell 2.3 comes with a lot of predefined templates. They are all stored in the file POVSHELL.TPL. You may edit these files to change the pre-defined templates or to add new ones. Refer to section A.5 to get a description of the file format. Appendix C. Warnings and errors ------------------------------- C.1 Output-file exists and CONTINUE is set to NO! OK to overwrite? This message occurs when the output-file you have specified already exists, and the continue flag is set to NO, preventing you from unintentionally overwriting the output-file. If you really want to overwrite it, just press RETURN. If you want to keep it, press ESCAPE, select Run again and enter a different outputfile-name. C.2 DOS-Error xxx occured on execute! Check execution path in SETUP|DIRECTORIES... This message occurs when POVRAY.EXE could not be executed properly. A possible reason is a wrong execution path entered in the Setup|Directories-dialog-box. C.3 PovRay completed successfully. Just an informational message. It says that ... (you guessed it!) C.4 Error(s) reported by PovRay! Possible reasons: Syntax errors in the script, unaccessible include files or bitmaps, ... Look at PovRay's error messages, check the include-path. C.5 Trace aborted. This message pops up when you had the +x option enabled and interrupted the trace by hitting a key. C.6 Not enough memory for this operation. Occurs when you opened too many files, or when you try to open a file that is too big. Note: File-size is limited to 64 KB. C.7 Can't open help file. The help file POVSHELL.HLP is missing. Be sure to copy it to the PovShell-directory. There are a lot more error messages, but they are all self-explaining... Appendix D. Command line parameters ----------------------------------- Calling syntax is: POVSHELL [file1 [file2 [...]]] [/B] [/Q] file1, file2 etc. will be automatically opened by PovShell. This can be used to automatically start PovShell from the Windows-filemanager or the MS-DOSShell by associating it with the .POV file-extension. Double-clicking on a POV-file will then launch PovShell with that POV-file. Switches: /B runs PovShell with a black&white color-palette /Q don't display About-box at program startup Appendix E. Contacting the author --------------------------------- If you have questions or comments on PovShell feel free to contact me! For information on how to do this read the file FEEDBACK.DOC! Thanks for your interest in POVSHELL. Enjoy the program! Andreas Peetz 12-07-1994