home *** CD-ROM | disk | FTP | other *** search
/ Ray Tracing Box / RAY_CD.mdf / raytrace / povshell / povshell.doc < prev    next >
Text File  |  1994-01-17  |  22KB  |  531 lines
  1. ==============================================================================
  2.                  POVShell Version 2.0
  3.              A Development Environment for POV-Ray
  4.             by Andreas Peetz [100101,1670]
  5. ==============================================================================
  6.  
  7. Contents:
  8.    1. Introduction
  9.    2. Installation/Quick start
  10.    3. Dialog elements
  11.    4. Menus, Commands and Hot keys
  12.    5. Editor keys
  13.    6. Option Quick keys
  14.    7. Special files and file formats
  15.    8. Warnings and errors
  16.    9. Distribution policy
  17.   10. Thanks
  18.   11. Contacting the author
  19.  
  20.  
  21. 1. Introduction
  22. ---------------
  23.  
  24. The 'Persistence of Vision Ray Tracer' (POV-Ray) is nowadays the most
  25. sophisticated and best known non-commercial raytracing-program.
  26. Its original authors, David Buck and Aaron Collins, and all the members
  27. of the POV-Ray team have done (and are still doing) a pretty good job
  28. on that program. I'd like to thank these guys for the many hours of
  29. pleasure that I'm having with POV-Ray and the brilliant pictures produced
  30. by it!
  31.  
  32. This description of the POVSHELL-program assumes that you are
  33. familiar with using POV-Ray or at least own a version of
  34. the POV-Ray-program. The actual version of PovRay is 2.1.
  35. PovShell will also work with earlier versions and even with the
  36. original DKB-Raytracer.
  37.  
  38. POV-Ray is designed to be a 'command-line-program', this means that you
  39. have to supply all of its parameters on the command-line when calling
  40. the program. This is fine for batch-processing, however, if you are
  41. writing your own POV-Ray-scene-scripts, you have to run the program
  42. repeatedly for quick preview-traces in order to test your scripts and
  43. different parameter settings. You will soon get tired of typing the same
  44. command-line over and over.
  45. To become rid of that I wrote POVSHELL, a user-friendly easy-to-use
  46. interface to POV-Ray. With POVSHELL you can
  47.   a) load and edit one or more POV-files,
  48.   b) set all raytrace-parameters via pulldown-menus
  49.      and option-windows
  50.   c) and finally call POV-Ray to trace the scene-file you are
  51.      currently editing with the parameters you have set.
  52.  
  53. POVSHELL was developed using the Turbo Vision-features of Turbo Pascal 6.0.
  54. Turbo Pascal and Turbo Vision are registered trademarks of Borland
  55. International, Inc.
  56.  
  57.  
  58.  
  59. 2. Quick Start
  60. --------------
  61.  
  62. 2.1 Installation
  63. The following files have to be copied to a directory of your choice (e.g.
  64. the direcory of the POV-Ray-program):
  65.   POVSHELL.EXE (the executable)
  66.   POVSHELL.HLP (the help file)
  67.   *.TPL        (template files) 
  68. That's all!
  69. Note: If you are upgrading from version 1.0 of PovShell, you may replace the
  70.       old POVSHELL.EXE-file. Version 2.0 is fully compatible to version 1.0,
  71.       i.e. you can continue to use the DEF-files saved with PovShell 1.0.
  72.  
  73. 2.2 Running the program for the first time
  74. Note: Since version 2.0 context-sensitive help is available everywhere
  75.       in PovShell. Just press F1! For information on how to use the
  76.       Help system press F1 twice.
  77. Start POVSHELL.EXE from the DOS-prompt. If this is the very first time you
  78. are running POVSHELL, a dialog box will pop up where you have to specify
  79. the default-POV-file-path, the default POV-Ray-output-path and the name of
  80. the POV-Ray-executable.
  81. This dialog-box can be activated later again via the Setup|Directories-
  82. menuitem (see. 4.5). The information you enter will be saved in a file
  83. and loaded whenever you run POVSHELL again. Close the box by pressing
  84. ENTER or clicking the OK-button.
  85. You will then see a desktop-screen with a menu-line at the top and a
  86. status-line a the bottom. If you are familiar with the IDE of Turbo-Pascal
  87. or any other Turbo-Language, you will 'feel at home' at once.
  88. There are three ways to activate the menu-items:
  89. a. Hold down the ALT-Key and press the red-typed character of the item.
  90.    Example: To open the 'File'-menu hold down ALT and F.
  91. b. Press the F10-Key. You can then select an entry of the Top-menu-line
  92.    with the cursor-keys. Press RETURN to activate it.
  93. c. If you have a mouse and a mouse-driver loaded (you will then see the
  94.    mouse-pointer on the screen), just move the mouse-pointer to the menu-
  95.    item and click on it.
  96. Some commands can be activated by 'Hot keys', e.g. the File-open command
  97. can be activated by pressing F3. All the Hot keys are listed at the bottom-line.
  98. For now, press F3 to open a POV-file. A file selection box will appear.
  99. Walk through the directories and pick one of the POV-files. If you are
  100. confused now and don't know how to do this, refer to section 3 for further
  101. assisstance.
  102. Once you have opened a POV-file you will find it loaded into an editor-
  103. window, where you can work on it (or not). For a description of the editor-
  104. commands refer to section 5.
  105. Now use the 'Options'-menu-items to set the trace-parameters. Assuming that
  106. you are familiar with POV-Ray, you will certainly know the meaning of the
  107. options and selections that are listed in the various dialog boxes. Again
  108. further explanations can be found in section 4.
  109. To trace the picture select the 'Run'-menu-item or just hold down the Ctrl-
  110. key and press F9. If you have chosen to produce an output-file you will
  111. be asked to name the output-file and then POV-Ray will be called with the
  112. parameter-settings you have selected.
  113. After tracing you will be returned to the POVSHELL-interface.
  114. You may exit POVSHELL at any time by selecting 'Exit' from the 'File'-menu
  115. or by pressing ALT-X.
  116.  
  117. 2.3 Monchrome monitor support
  118. People who want or have to use PovShell with a B&W-display should use the
  119. commandline-switch /b to start the program. Type
  120.   POVSHELL /B
  121. at the DOS-prompt!
  122.  
  123.  
  124.  
  125. 3. Dialog Elements
  126. ------------------
  127.  
  128. The dialog-boxes offered by POVSHELL generally consist of three types
  129. of elements: check-boxes, radio-buttons and input-lines. To switch between
  130. the elements of a dialog-box use the TAB-key. To close a dialog-box
  131. and confirm the changes made in it, press ENTER or click on the OK-button.
  132. To close a dialog-box without changes press ESCAPE or click on the
  133. Cancel-button.
  134.  
  135. 3.1 Check-boxes [ ] [X]
  136. Check-boxes are used for turning on and off various tracing-options, e.g.
  137. anti-aliasing or the verbose-mode. If an option is turned off the check-
  138. box looks like this: [ ]. if it is turned on it looks like this: [X].
  139. Toggle with the space bar!
  140.  
  141. 3.2 Radio buttons ( ) ()
  142. Radio-buttons are used to select one (and only one) item out of a list
  143. of items, e.g. to select the output-format (TGA, Dump or RAW).
  144. If an item is selected the radio-button looks like this (), otherwise
  145. like this: ( ).
  146. Walk through the list with the cursor-keys, select one item with SPACE!
  147.  
  148. 3.3 Input-lines
  149. Whereever you have to enter a particular number (e.g. the output-file-
  150. buffersize) or a filename (e.g. the output-filename) you will be prompted
  151. for it in an input-line. Just type the values you want to use. If your
  152. input is incorrect or out of range it will be rejected!
  153.  
  154.  
  155.  
  156. 4. Menus, Commands and Hot keys
  157. -------------------------------
  158.  
  159. 4.1 File menu
  160. - Open... :   lets you select a POV-file that will be loaded into a
  161.           new editor window
  162. - New:        opens a new empty editor window
  163. - Save:       the file you are currently editing will be saved
  164. - Save as...: the file you are currently editing can be saved under a
  165.           name of your choice
  166. - DOS shell:  opens a DOS shell. Return by typing EXIT at the DOS-prompt!
  167. - Exit:       Leave program. If you have unsaved files open, you will be
  168.           prompted to save them.
  169.  
  170. 4.2 Edit menu
  171. - Undo:       lets you undo the last change you made to the current
  172.           editor window.
  173. - Cut:        cuts the selected text out of the current editor window and
  174.           places it in the clipboard. Select text by holding down SHIFT
  175.           and moving the cursor or by moving the mouse with the left
  176.           button pressed.
  177. - Copy:       copies selected text to the clipboard.
  178. - Paste:      inserts text from the clipboard to the current editor window
  179. - Show clipboard: shows the clipboard window. The clipboard is a special
  180.           editor window which is used to exchange text-blocks between
  181.           two 'normal' editor windows
  182. - Clear:      clears the selectes text from the current editor window.
  183.  
  184. 4.3 Search menu
  185. - Find...:    lets you find a string in the current editor window
  186. - Replace:    lets you find and replace a string by another string
  187. - Search again: finds a string that was searched for again.
  188.  
  189. 4.4 Window menu
  190. - Size/Move:  resize and move an editor window on the desktop
  191. - Zoom:       zoom an editor window to cover the whole desktop
  192. - Tile:       tile editor windows on the desktop
  193. - Cascade:    cascade them
  194. - Next window: switches to next editor window
  195. - Previous window: switches to previous editor window
  196. - Close:      closes the active editor window
  197.  
  198. 4.5 Options menu 
  199. - Output...:  (±Fx, ±C, ±B)
  200.           lets you specify the output-format, continue flag and output
  201.           -buffersize
  202.           Note: In version 1.0 of PovShell you also had to specify
  203.             the output-filename in this dialog-box. This has been
  204.             changed. You will now be asked for the output-file-name
  205.             each time you start a trace (see. 4.8 Run)
  206. - Display...: (±D, +W, +H)
  207.           for the specification of the display-adapter, image-width
  208.           and image-height
  209. - Trace...:   (+Q, ±A, ±J, +R, ±MB, +MS, +MV)
  210.           lets you specify the rendering-quality, anti-aliasing,
  211.           anti-aliasing-jitter and -number of rays, the bounding
  212.           slabs-option, symbol-table-size and version compatibility mode
  213. - Libraries...: (+L)
  214.           These are the paths that are passed to
  215.           POV-Ray via the +L option. Specify up to 10 paths,
  216.           separated by ;
  217. - Misc...: (±V, ±P, ±X, +K, +S(R), +SC, +E(R), +EC)
  218.           lets you toggle the verbose, pause after trace and
  219.           early exit-flags, a clock value, and start/end-rows/columns
  220.           of tracing
  221.  
  222. - Save options...: lets you save the currently selected tracing parameters
  223.           in a DEF-file.
  224. - Save Default options: saves options in the DEFAULT.DEF-file (see 7.2)
  225. - Retrieve options...: lets you retrieve parameter settings that were
  226.           saved before.
  227.  
  228. 4.6 Setup menu
  229. - Directories...:
  230.           1. Default POV-file-path: this is the directory POVSHELL
  231.          will change to when you choose to open a POV-file
  232.           2. Default-Output-path: this the directory where the output-files
  233.          will be written to unless you do not change the directory
  234.          when prompted for the output-file-name.
  235.          If you leave it blank, the default-output-path will be the
  236.          directory of the POV-file you want to trace
  237.           3. Executable path: This is the path to the executable
  238.          POV-Ray-program (normally POVRAY.EXE).
  239.          Specify the full file name, e.g. C:\POV\POVRAY.EXE.
  240. - Editor...:  1. Create Backup files: if you choose this item, the editor
  241.          will save a copy of each file you open using a BAK-extension
  242.           2. Insert-Mode: if selected the editor-cursor will be in
  243.          insert-mode on startup. You can toggle this by pressing
  244.          the Insert-Key or CTRL-V.
  245.           3. AutoIndent-Mode: if selected the editor will use the
  246.          autoindent mode, i.e. each time you begin a new line
  247.          the cursor will be placed in the column were the above
  248.          line starts. Good for writing structured scripts.
  249.           4. Save Desktop on exit: if selected PovShell will save the 
  250.          names of all open files on program-exit. They will then be
  251.          reopened automatically on the next startup (cf. 7.5)
  252. - Colors...:  Lets you customize the PovShell colors (look at the online help
  253.           for a detailed description of the dialog box!).
  254.           This command will not be available if you tell PovShell to use
  255.           the B&W-palette by using the commandline-switch /b !
  256.           
  257.  
  258. 4.7 Templates menu
  259. In this menu you get a list of predefined PovRay-templates. If you select
  260. e.g. the CAMERA-item the following will be inserted in the current POV-file
  261. at the actual cursor position:
  262. camera {
  263.     location < , , >
  264.     look_at  < , , >
  265. }
  266. Note: You can change the text of the templates by editing the related
  267.       TPL-file in the PovShell-directory. You can also create new Template-
  268.       files. They will then appear in the Templates-menu when you start
  269.       PovShell again.
  270.       In the TPL-files lines starting with a semi-colon will be ignored
  271.       by PovShell. So they can be used for comments.
  272.       The number of templates is actually limited to 22.
  273.  
  274. 4.8 Run
  275. Runs POV-Ray with the file you are currently editing and the actual
  276. parameters settings.
  277. If you have selected an output-format other than 'none' you will be
  278. asked to name the output-file before PovRay is launched.
  279. Default is:   Default Output-file path from SETUP|DIRECTORIES...
  280.         + the name of the POV-file you are tracing
  281.         + an extension that is generated from the output-format 
  282.  
  283. 4.9 About
  284. Displays the About-box that can be seen at program start.
  285.  
  286. 4.10 Hot-Keys
  287. - F1:       context sensitive help
  288. - F2:       save file
  289. - F3:       open file
  290. - Alt-F3:   close file
  291. - F5:       zoom editor window
  292. - Ctrl-F5:  size/move window
  293. - F6:       next window
  294. - Shift-F6: previous window
  295. - Ctrl-F9:  run
  296. - F10:      menu
  297. - Alt-X:    Exit
  298.  
  299.  
  300.  
  301. 5. Editor keys
  302. --------------
  303.  
  304. The Editor uses WordStar-compatible key-commands:
  305.  
  306. 5.1 Cursor movement
  307. Ctrl-E: cursor up           Ctrl-X: cursor down
  308. Ctrl-S: cursor left         Ctrl-D: cursor right
  309. Ctrl-A: word left           Ctrl-F: word right
  310. Ctrl-R: scroll page up      Ctrl-C: scroll page down
  311.  
  312. 5.1 Delete commands
  313. Ctrl-G: delete character under the cursor
  314. Ctrl-H: delete character left of the cursor
  315. Ctrl-T: delete word beginning at cursor position
  316. Ctrl-Y: delete actual line
  317.  
  318. 5.2 Quick keys
  319. Ctrl-Q-A: Replace a text string        Ctrl-Q-C: Go to the end of the text
  320. Ctrl-Q-D: Go to the end of the line    Ctrl-Q-F: Find a string
  321. Ctrl-Q-H: Delete line up to cursor     Ctrl-Q-R: Go to the top of the text
  322. Ctrl-Q-S: Go to line start             Ctrl-Q-Y: Delete line beginning at cursor
  323.  
  324. 5.3 Block keys
  325. Ctrl-K-B: Mark start of Textblock      Ctrl-K-C: Paste block from Clipboard
  326. Ctrl-K-H: Toggle block-highlight       Ctrl-K-K: Copy block to Clipboard
  327. Ctrl-K-Y: Cut block to Clipboard
  328.  
  329. 5.4 Others
  330. Ctrl-L: Search again
  331. Ctrl-V: Toggle Insert mode
  332. Ctrl-M: New line (=RETURN)
  333.  
  334.  
  335.  
  336. 6. Option Quick keys
  337. --------------------
  338.  
  339. You have now a quick key access to all PovRay-options. You need not to use
  340. the Options...-menu, if you remember the letter of the PovRay-option you
  341. want to change, just press Ctrl-O and then this letter (e.g. Ctrl-O-V to
  342. change the verbose option). Then the appropiate dialog box will pop up
  343. and lets you make your changes.
  344.  
  345. Ctrl-O-A: AntiAliasing            Ctrl-O-B: Buffersize
  346. Ctrl-O-C: Continue                Ctrl-O-D: Display-Adapter
  347. Ctrl-O-E: End-Row/-Column         Ctrl-O-F: Outputformat
  348. Ctrl-O-H: ImageHeight             Ctrl-O-J: AAJitter
  349. Ctrl-O-K: Clock-Value             Ctrl-O-L: Library-paths
  350. Ctrl-O-M: Bounding slabs          Ctrl-O-P: Pause when finished
  351. Ctrl-O-Q: Quality                 Ctrl-O-R: Number of AA-rays (to be squared)
  352. Ctrl-O-S: Start-Row/-Column       Ctrl-O-V: Verbose
  353. Ctrl-O-W: Image Width             Ctrl-O-X: Allow early exit
  354.  
  355.  
  356.  
  357. 7. Special files and file formats
  358. ---------------------------------
  359.  
  360. 7.1 POVSHELL.CFG
  361. POVSHELL will store the Default-POV-file-path, the output-path, the
  362. path to the executable, its editor settings and color informations
  363. in the file POVSHELL.CFG.
  364. DO NOT EDIT THIS FILE! Use the appropiate commands and menus in POVSHELL to
  365. change the parameters.
  366. POVSHELL.CFG will be stored in the directory where POVSHELL.EXE resides.
  367. It will be read by the program every time it is started and it will be
  368. written every time you exit it.
  369.  
  370. 7.2 DEFAULT.DEF
  371. On startup, POVSHELL will scan the directory where POVSHELL.EXE resides
  372. for a file named DEFAULT.DEF. If it is found the options stored in it
  373. will be loaded.
  374. There is no need to edit this file! If you want to save or change startup
  375. options, select the Options|Save default options-menuitem.
  376.  
  377. 7.3 DEF-File formats
  378. Note:
  379. a. If you have DEF-files written on your own you can load then into POVSHELL
  380.    via the Options|Retrieve Options...-menuitem!
  381. b. If you have saved options from POVSHELL via the Options|Save Options...-
  382.    menuitem into a DEF-file you can also use these files outside POVSHELL by
  383.    typing
  384.        POVRAY +i<inputfile> +o<outputfile> <DEF-file>
  385.    at the DOS-prompt.
  386. c. If you save options only those parameter settings will be written into
  387.    the DEF-file which are NOT the POV-Ray-DEFAULT settings!
  388.  
  389. 7.4 TPL-Files (Templates)
  390. Text-files with a TPL-extension will appear in the PovShell-Templates
  391. menu. If you select an item of the Templates-menu the related file will
  392. be inserted at the current cursor-position.
  393. You may edit the pre-defined TPL-files or create new ones using the PovShell-
  394. Editor or any other ASCII-text-file-editor.
  395. For more information on TPL-files see section 4.7.
  396.  
  397. 7.5 POVSHELL.DSK
  398. This is the PovShell-Desktop file. If you have chosen the 'Save Desktop
  399. on exit'-item in the Setup|Editor...-dialog-box all open files (i.e. their
  400. names) will be saved in the Desktop-file when you exit the program.
  401. On the next PovShell-startup the files listed in the Desktop-file will be
  402. automatically reopened.
  403. NEVER EDIT this file! 
  404.  
  405. 7.6 POVSHELL.HLP
  406. This is the PovShell-helpfile. It includes all the help texts and binary
  407. coded information on indices and hyper-links. NEVER EDIT this file!
  408. PovShell will still work when the help file gets lost, but it *will*
  409. crash if it gets corrupted!
  410.  
  411. 7.7 Temporary files
  412. Every time you call 'Run' from the POVSHELL-menu the following will happen:
  413.  1. The contents of the active editor-window will be saved in a temporary
  414.     file named $SHELL$.POV.
  415.  2. The actual parameter settings will be saved in a temporary file
  416.     named $SHELL$.DEF.
  417.  3. POVRAY.EXE is called using the temporary files.
  418.  4. The temporary files are deleted.
  419. Normally the temporary files are stored in the actual directory. However,
  420. if you have a DOS-environment-variable TEMP defined, the files will be
  421. written to the directory where TEMP is pointing to.
  422. If you want to use this feature place a command like
  423.   SET TEMP=C:\TEMP
  424. in your AUTOEXEC.BAT and make sure that the specified directory exists!
  425.  
  426.  
  427.  
  428. 8. Warnings and errors
  429. ----------------------
  430.  
  431. 8.1 Output-file exists and CONTINUE is set to NO!
  432.     OK to overwrite?
  433. This message occurs when the output-file you have specified already exists,
  434. and the continue flag is set to NO, preventing you from unintentionally
  435. overwriting the output-file. If you really want to overwrite it, just press
  436. RETURN. If you want to keep it, press ESCAPE, select Run again and enter
  437. a different outputfile-name.
  438.  
  439. 8.2 DOS-Error xxx occured on execute! Check execution path in
  440.     SETUP|DIRECTORIES...
  441. This message occurs when POVRAY.EXE could not be executed properly. A possible
  442. reason is a wrong execution path entered in the Setup|Directories-dialog-box.
  443.  
  444. 8.3 PovRay completed successfully.
  445. Just an informational message. It says that ... (you guessed it!)
  446.  
  447. 8.4 Error(s) reported by PovRay!
  448. Possible reasons: Syntax errors in the script, unaccessible include files 
  449. or bitmaps, ... Look at PovRay's error messages, check the include-path.
  450.  
  451. 8.5 Trace aborted.
  452. This message pops up when you had the +x option enabled and interrupted
  453. the trace by hitting a key.
  454.  
  455. 8.6 Not enough memory for this operation.
  456. Occurs when you opened too many files, or when you try to open a file that
  457. is too big.
  458. Note: File-size is limited to 64 KB.
  459.  
  460. There are a lot more error messages, but they are all self-explaining...
  461.  
  462.  
  463.  
  464. 9. Distribution policy
  465. ----------------------
  466.  
  467. POVSHELL Version 2.0 is FREEWARE. This program may be used, copied and
  468. disitributed without charge.
  469. However, it is strongly recommended that the code and the documentation of
  470. the program remain unchanged when distributed.
  471. If you decide to upload POVSHELL to your favourite BBS or to an internet
  472. site, please supply ALL the files that came with the program and send me
  473. a short message containing the date of upload and the name, location and
  474. phone number of the BBS, resp. the name and address of the internet-server.
  475.  
  476. POVSHELL consists of the following files:
  477.   POVSHELL.EXE (the executable)
  478.   POVSHELL.DOC (this file)
  479.   WHATSNEW.DOC (What's new in this release)
  480.   README.1ST   (important notes)
  481.   AREA_LIG.TPL (pre-defined Template-files)
  482.   BOUNDED.TPL
  483.   BOX.TPL
  484.   CAMERA.TPL   
  485.   CLIPPED.TPL
  486.   COLORMAP.TPL
  487.   CONE.TPL
  488.   FINISH.TPL
  489.   HEIGHT.TPL
  490.   IMAGE_MA.TPL
  491.   LIGHT.TPL
  492.   LOOKS_LI.TPL
  493.   NO_SHADO.TPL
  494.   PLANE.TPL
  495.   SPHERE.TPL
  496.   SPOTLIGH.TPL
  497.   TEXTURE.TPL
  498.  
  499.  
  500.  
  501.  
  502. 10. Thanks
  503. ----------
  504.  
  505. I want to thank all the people who helped me to improve POVShell since
  506. the last release in Dec.1993.
  507. Special thanks are going to Dan Farmer for a critical review of version 1.0
  508. and to Webb Moore for his idea of adding the template-macro feature and
  509. supplying the pre-defined TPL-files.
  510.  
  511.  
  512.  
  513. 11. Contacting the author
  514. -------------------------
  515.  
  516. If you have anything to say about the POVSHELL-program please do not hesitate
  517. to contact me!
  518. Questions, positive and negative comments, suggestions on improvements and
  519. especially bug reports are always appreciated!
  520. If you are on CompuServe, place a message in the 'POV Sources'-section of the
  521. GRAPHDEV-forum or contact me via
  522.  
  523. CompuServe Mail:     [100101,1670]
  524. or Internet Mail:    peetz@biochem.hoechst-ag.d400.de
  525.  
  526. Internet Mail is preferred and read daily!
  527.  
  528. Thanks for your interest in POVSHELL. Enjoy the program!
  529.  
  530.                                Andreas Peetz
  531.