home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR37 / PMPOVF.ZIP / POVFRAME.DOC < prev    next >
Text File  |  1993-10-06  |  17KB  |  359 lines
  1.  
  2.                       POVFrame 1.0 For OS/2 2.x 
  3.  
  4.                     Copyright (c) 1993  Bill Pulver
  5.    
  6. ------------------------------------------------------------------------------
  7.  
  8. Thank you for trying POVFrame. This program enables you to use the FreeWare
  9. raytracing program POV-Ray from the OS/2 2.x DeskTop. Most of the functions
  10. needed to effectivly use POV-Ray in the WPS environment are available from
  11. the POVFrames user interface. 
  12.  
  13.        This program is being distributed as shareware!!
  14.  
  15. A registration fee of $20 (US) is required if the program is used beyond a 
  16. 30 day trial period. THANK YOU! See ORDER.DOC for further information.
  17.  
  18. NOTE: This program is NOT a "product" of the POV-Ray team. I use OS/2 for
  19.       my main machine & thought others would find a POV-Ray shell usefull.
  20.       Please dont bother others on the team with questions about this 
  21.       program! <g> See ORDER.DOC for more info.
  22.  
  23. Also: The OS/2 compile of POV-Ray seems to be less "tolerant" of math errors
  24.       than the "official" ICB compile is. It will sometimes crash on large, 
  25.       complex image files. If this happens try using the "official" Code 
  26.       Builder compile to render your image.
  27.  
  28.  
  29.  
  30.  
  31.  
  32.        ------------
  33.        Installation
  34.        ------------
  35.  
  36.     Installation of the program is fairly simple. The VROBJ.DLL file is
  37. the VX-Rexx function library, it may be placed in a directory in your OS/2
  38. LIBPATH statement (D:\OS2\DLL is good) or it may simply be left in the same
  39. directory as the POVFrame executable file. (POVFRAME.EXE)
  40.  
  41.     A third party OS/2 support program called STARTD.EXE is required
  42. to start the DOS sessions since a value larger than OS/2's default
  43. must be used for DPMI_MEMORY_LIMIT. STARTD will start a DOS session with
  44. the values in the POV.INI file. They may be changed the same as if they
  45. were being set in the DOS Session notebook setup by editing POV.INI
  46. with a text editor. DO NOT DELETE POV.INI or the DOS version of POV-Ray
  47. will not run. For convienece the original BBS distribution file of STARTD
  48. is included with POVFrame. It is copyrighted but is freely distributable.
  49.    By default POVFrame expects the DOS executable & the OS/2 executable
  50. to be in the same directory as POVFrame. This is the simplest & most reliable
  51. way to use the program but different paths may be entered with POVFrames
  52. "defaults" pulldown as described above. STARTD may also be left in the same
  53. directory or placed in a directory that is pointed to by your OS/2 PATH
  54. statement in your OS/2 CONFIG.SYS file.
  55.  
  56.  
  57.  
  58.  
  59.  
  60. USING POVFrame
  61. --------------
  62.  
  63.    ----------------
  64.    DeskTop Options
  65.    ----------------
  66.  
  67.     If you are familiar with the options available for running POV-Ray
  68. most of the options on the DeskTop should be old hat for you. For further 
  69. information on POV-Ray and the options available please consult the POV-Ray
  70. documentation distributed in POVDOC.ZIP. POVFrame will build a new POV-Ray
  71. DEF file for each POV-Ray image run so multiple images with different 
  72. settings may be started. POVFrame uses a DEF file named POVDOS.DEF for the
  73. DOS compile, POVOS2.DEF for the OS/2 compile and POVANIM.DEF for animation
  74. runs. An OS/2 text mode compile of POV-Ray is included with this program.
  75. It IS NOT shareware but freeware & registration of POVFrame does not relate 
  76. to it. It has been slightly modified from the distribution source code in
  77. that all errors and the final image STATS are sent to STDERR in order to
  78. capture them in the VX-Rexx console, the regular POV-Ray run time
  79. info, credits, +v verbose line info etc are sent to STDOUT & will appear
  80. in the OS/2 session window during the image run. Errors and image stats
  81. may be saved to a disk file from the VX-Rexx console using an option in
  82. the upper left "frame" button. The standard POV-Ray Team release DOS compile
  83. distributed as POVIBM.EXE may be used for the DOS version.
  84.  
  85.  
  86. The following describes the options, installation & use of POVFrame:
  87.  
  88.                      ------------------------
  89.                          POVFrame Options
  90.                      ------------------------
  91.  
  92.  
  93. Output Buffering:
  94. -----------------
  95.     This group box allows you to select whether you want POV-Ray to 
  96. buffer the image as it is rendered. The size of the buffer is entered in
  97. the dialog box. The "Disable Image Buffering" checkbox enables & disables 
  98. this option for POV-Ray image runs. Note that using an image buffer can 
  99. significantly increase rendering speed by restricting disk writes. The 
  100. default is to use buffering with a 512K buffer.
  101.  
  102. Image Run Parameters:
  103. ---------------------
  104.     This group box controls the resolution of the image run and allows
  105. the use of POV-Ray's ability to render only a portion of the complete image.
  106. The "Do A Partial Render" checkbox enables & disables this option. The 
  107. "Percentage Partial" checkbox toggles between doing a partial render based
  108. on physical starting/ending lines & columns of the image or based on a 
  109. percentage of the image width & height. Valid values for a render based on
  110. the physical resolution of the image are 0 to Image Width & 0 to Image Height.
  111. Valid values for percentage based renders are 0 to 99.9%. The values for all
  112. these options are simply entered into the dialog boxes.
  113.  
  114. Output File Type:
  115. -----------------
  116.     This group box of Radio Buttons selects the file type to be written.
  117. Just click on the one you want.
  118.  
  119. Image File Selected:
  120. --------------------
  121.     This dialog box is an informational box to tell you what image file
  122. the program will render. The file may be selected from the "Files" pulldown
  123. menu in the upper left, the "Files" button in the Image File Selected group
  124. box, or by pointing to the entry field with the mouse cursor, clicking mouse
  125. button 1 to move focus to that dialog box & pressing a key on the keyboard.
  126.  
  127. Other Options:
  128. --------------
  129.     This group box contains checkboxes and radio buttons for the various
  130. commonly used POV-Ray options. See the POV-Ray docs for specific information
  131. on what each one does. A "check" in a checkbox or radiobutton signifies that 
  132. option is enabled for the next image run. Note that the "Display" option is
  133. valid ONLY with a DOS compile. (It will work with either the "official" POV-
  134. Ray Teams ICB compile or a Watcom 9.5 compile.)  
  135.  
  136. Use the "Verbose" option for the OS/2 compile supplied with POVFrame.
  137.                   
  138. Image Quality & Anti-Aliasing:
  139. ------------------------------
  140.     These dialog boxes set the values for POV-Rays quality and anti-
  141. aliasing features. The quality levels are selected by running thru POV-Rays
  142. valid options using a "spin-button". The values for Anti-Aliasing are 
  143. entered via the dialog boxes in this area. The Disable Anti-Aliasing checkbox
  144. will disable AA for the next image run. By default it is disabled since
  145. you will probably only want to use it for a final "high quality" image run.
  146.  
  147. OS/2 GO! and DOS GO!:
  148. ---------------------
  149.     POVFrame will start either a DOS compile of POV-Ray or an OS/2 compile
  150. of POV-Ray. The POV-Ray teams ICB (DOS) compile of POV-Ray 2.0 has the ability
  151. to render an image of any resolution to a WPS desktop window by using the 
  152. VGA 320x200x256 mode as the display option. (+d1 POV-Ray option) The "Display
  153. Image While Rendering" radio button option is valid ONLY for the DOS compile
  154. at the moment. The OS/2 compile supplied with POVFrame will display the 
  155. verbose "current line being rendered" option to the OS/2 session window during
  156. the image run. Errors and the image trace stats are written to the VX-Rexx 
  157. consol handler and may be reviewed and saved from there. (Saved from the upper
  158. left buttons pulldown menu.) Upon completion rendered image files will have
  159. the same name as the image "source" & the appropriate extension for the type
  160. of file written. For example, using the program defaults for paths & such,
  161. D:\POVRAY\BLOB.POV will render to D:\POVRAY\BLOB.TGA if the TGA file type is 
  162. selected. The VX-Rexx console window must be closed "manually" after POVFrame
  163. is terminated. You may also save the contents of the VX-Rexx console to a
  164. file. This makes for a good way to save image stats if desired.
  165.  
  166.  
  167.  
  168.    --------------
  169.    PullDown Menus
  170.    --------------
  171.  
  172. Files:
  173. ------
  174.     The "Files" pulldown supplies file services. Image files to be rendered
  175. may be selected from here. Image files to be edited may also be selected as
  176. well as deleted. 
  177.  
  178.  The "Select Image File to Render" option is identical in function to the 
  179. "Files" pushbutton in the "Image File Selected" groupbox on the desktop 
  180. explained earlier.
  181.  
  182.  The "Edit POV-Ray File" option selects a POV-Ray image source file for editing
  183. and calls OS/2s "built in" editor, EPM.EXE (The Enhanced Editor), to actually
  184. edit the image file. Multiple files may be opened in different windows to
  185. allow cut 'n paste editing of entire image file sets. Due to a limitation
  186. in the file selection dialog there can only be 1 default file mask. In this 
  187. case *.POV is used. Other masks may be entered manually in the "Open
  188. Filename:" dialog box at the top to select *.INC or other POV-Ray image file
  189. extensions. If a filename that does not exist is entered EPM will open a file
  190. by that name for editing. New image files may be created that way.
  191.  
  192.  The "Delete A File" dialog may be used to delete unwanted or outdated
  193. files. By default all files are displayed in the dialog. A second dialog
  194. box will open to -make sure- you want to delete the file selected.
  195.  
  196.  
  197. Defaults:
  198. ---------
  199.  
  200. All of the following are stored in the POVFRAME.INI file and, after setup,
  201. are loaded each time the program is started.
  202.  
  203.     The defaults pulldown allows initial settings for POVFrame to be
  204. set & saved as well as POV-Ray options that are less frequently changed.
  205. Items such as your POV-Ray image "source" files path and POV-Ray library 
  206. directories. (Up to 4) All of these options are saved in the POVFRAME.INI
  207. file and will be loaded each time the program is started. All path names
  208. must be fully qualified.
  209.  
  210.  The "POV-Ray Source Path" option allows entry of the path to your POV-Ray
  211. image "source" files directory. This is the directory where your IMAGE 
  212. SOURCE FILES are located, NOT the POV-Ray program it's self. Enter a fully 
  213. qualified path name including a trailing backslash. 
  214. EXAMPLE: D:\POVRAY\IMAGES\
  215.  
  216.  The "Library Paths" option opens a submenu that allows entry of up to 4
  217. library directories for POV-Ray. Again, fully qualified paths *must* be
  218. entered.
  219.  
  220.  The "DOS (& OS/2) EXE Defaults" options allow you to seperate your DOS and 
  221. OS/2 EXECUTABLES by specifying a specific path to your DOS/OS2 executable 
  222. file and a directory that all your DOS/OS2 rendered images should be placed 
  223. in upon completion. 
  224.  By default that program expects both the OS/2 and DOS executables to be in 
  225. the same directory as POVFRAME.EXE. Also, by default, rendered images are 
  226. placed in the same directory as the image "source" file they are rendered
  227. from. These options are provided for "house keeping" if you'd like to use 
  228. them to keep things a little more "organized". They also allow the 
  229. use of both the OS/2 and DOS compiles to render the same image at the same
  230. time. (If this is attempted with the program defaults both compiles will
  231. attempt to write the image to the SAME file!!!... Leads to some wierd results
  232. sometimes.)
  233.  
  234.  The "OS/2 EXE Defaults" allows the same options to be set for the OS/2
  235. executable.
  236.  
  237.  The "View Program" option allows the entry of the path too, and name of, an
  238. *external* OS/2 image viewer and/or post processor. A fully qualified path
  239. must be entered. Some options that are available for this are PMVIEW, PMJPEG
  240. and JOEVIEW, all of which are also shareware programs and may be obtained
  241. from many BBS's and On Line services. I've tried them all & they all work
  242. quite well. The program selected by this option is called from a files 
  243. dialog under the "External" pulldown menu. Just about any OS/2 program that 
  244. can have the image file name passed to it on the command line may be used 
  245. here.
  246.  
  247.  The "Post Processor Program" option does the same thing as the View Program
  248. option but the files used for this one may be DOS files. Since I use
  249. a TSENG ET4000 based HiColor/TrueColor video card in my machine here I use 
  250. TGVIEW.EXE by John Swenson for this option. It allows me to click on the TGA 
  251. file I'd like to look at in the files dialog presented under the "External"
  252. pulldown. As with the "View Program" option above, just about any DOS program
  253. may be used for this option. The DOS session started when the program is 
  254. invoked under the "External" pulldown is a FULL SCREEN session. This allows
  255. use of HiColor or TrueColor hardware and the DOS progams that support it.
  256. PICLAB and other image processors may also be started from here. The idea
  257. between the "View Program" and "Post Processor Program" options is to allow
  258. as many OS/2 and DOS programs as possible to be called directly from the 
  259. POVFrame desktop & have the name of an image file passed directly to them.
  260. Again, fully qualified path names and EXE names should be used for both of
  261. these options.
  262.  
  263.  The "External" option actually calls & executes the programs whose names
  264. and paths have been entered as described above.
  265.  
  266.  
  267. SnapShot
  268. ---------
  269.  
  270.  The "SnapShot" option will examine the >>> CURRENT STATE <<< all of the 
  271. entry boxes, radio buttons and check boxes on the desktop (with the exception
  272. of the Partial Image rendering paramaters) and save them to a defaults file
  273. named POVSNAP.INI. These settings will then be loaded as the DeskTop defaults 
  274. for future program startups. For example, say you'd like a default image buffer
  275. of 200K, display during render with a pause at completion, and a quality
  276. setting of +q5. Set these options up this way by entering the appropriate
  277. values & punching the right buttons, then run the SnapShot option. From then
  278. on, when you start the program, these items will be set up this way. It does
  279. slow down program startup by a few seconds though. To return to the programs 
  280. "built in" defaults DELETE the file POVSNAP.INI.
  281.  
  282.  
  283. Animation:
  284. ----------
  285.     This option is a VERY BASIC animation loop generator that uses the 
  286. POV-Ray 2.0 "clock" option to pass frame information to the program. It's 
  287. currently a very simple system. Frame and clock values may be entered in
  288. the entry boxes. The clock increment value for the animation may be entered
  289. manually or the program will calculate even steps for the clock increment
  290. when the AutoCalculate checkbox is "checked'. 
  291.  
  292. BE VERY CAREFULL TO ENTER ** ONLY ** NUMBERS WHEN THE AUTOCALCULATE IS "ON".
  293.  
  294. The program will ignore a minus sign entered as the FIRST charactor in the 
  295. entry field to allow negative numbers to be entered. REXX's math support is 
  296. quite limited, the program will crash if an Alpha charactor is entered since 
  297. the math for undefined variables (which is how REXX interprets it) is 
  298. undefined. Currently ONLY the DOS compile of POV-Ray is used for animation 
  299. generation. (POVFrame writes out a DOS batch file with a seperate command 
  300. line for each frame to be generated.) The output image files will be numbered 
  301. sequentialy based on the frame values and the first 4 charactors of the image
  302. file name. To facilitate simpler use of programs such as Dave Masons "DTA" 
  303. frames numbered from 0 to 9 will have 2 leading zeros prepended and frames 
  304. numbered from 10 to 99 will have one 0 prepended. 
  305.  
  306. I.E. Frames are numbered xxxx000, xxxx001, xxxx002... xxxx035... xxxx999 etc..
  307.  
  308. It's not much but it does make for -easy- linear animation generation. 
  309. Simply replace the value that you would like to vary in your POV-Ray 2.0
  310. image "source" file with the word "clock" & the values will be passsed to it.
  311. EXAMPLE:
  312.        Used to vary the z position of the camera in this case.
  313.  
  314.                   camera {
  315.                           location  <-5, 8, clock>
  316.                           direction <0, 0, 1.2071>
  317.                           look_at   <0, 0, 0>
  318.                           }
  319.  
  320.         
  321. --- If you have any ideas on anything to add here, or the rest of the program for that
  322.     matter, I'd like to hear them!
  323.  
  324.  
  325. Help:
  326. -----
  327.  
  328.     The "DOCS" are still being worked on. I'm hoping to have a full 
  329. INF version of POV-Ray 2.0's doc files hooked into the program here. 
  330. *** Lots of work to convert the DOCS though.
  331.  
  332.     "About" is just that.
  333.  
  334.  
  335.  
  336.  
  337.  
  338. This gives an intro to the program. The best way to get the feel of it is
  339. to, of course, USE it. Expirement & have fun!!!
  340.  
  341.  
  342. Thanks for your time:
  343. Bill Pulver 
  344.  
  345. Please send bug reports & suggestions to one of the following E-MAIL addresses.
  346. They are listed in desending order of frequency of usage, just not enough
  347. hourse in the day......
  348.  
  349. InterNet folks, PLEASE include your "return address" in the body of your
  350. message. Deciphering the routing headers can sometimes be a difficult task!
  351. <G>
  352.  
  353. CIS     : 70405,1152                   <------ Most often used!
  354. InterNet: 70405.1152@compuserve.com
  355. AOL     : BPulver
  356. Delphi  : BILLP
  357. Genie   : B.Pulver
  358. Prodigy : NCCJ93A
  359.