home *** CD-ROM | disk | FTP | other *** search
/ Borland Programmer's Resource / Borland_Programmers_Resource_CD_1995.iso / code / graphics / povdoc / poverr.doc < prev    next >
Encoding:
Text File  |  1995-05-19  |  16.7 KB  |  416 lines
  1.                   Persistence of Vision Raytracer
  2.                           Version 1.0 
  3.                     Run-Time Error Documentation
  4.                   -------------------------------
  5.                    By Eduard Schwan & Drew Wells
  6.  
  7. This document lists all the errors that POV-Ray might generate while trying
  8. to read and render a scene file and attempts to give a better explanation 
  9. of why the error occured than the program provides at run-time.
  10.  
  11. If a run-time error is not found in this list, it is probably a system
  12. or executable error. These errors are not handled by POV-Ray, rather, the
  13. system takes over and generates the error and aborts the program.
  14. These messages usually look quite different than the normal POV-Ray
  15. error messages and should be easy to recognize. Other than math errors,
  16. they usually indicate that you need to fix somthing with your computer,
  17. rather than a bug in POV-Ray.
  18.  
  19. MATH ERRORS: POV-Ray renders images using complex mathematical routines,
  20.              and sometimes these calculations exceed the capabilities
  21.              of the computer. When this happens a math error is generated
  22.              that usually reads something like, floating point error, or
  23.              stack underflow.
  24.              Often this can be solved by changing the viewpoint slightly
  25.              or changing parameters slightly.
  26.              
  27.              DIVIDE BY ZERO: There are two easy ways to generate a 
  28.              divide by zero error that you should avoid,
  29.                 
  30.                 SCALE BY ZERO: Never scale any component by zero
  31.                    ie. scale <2 0 2> will cause an error
  32.                    To leave a component the same size, scale by 1.
  33.                 ROUGHNESS ZERO: The roughness component must be greater
  34.                    than zero. And on some computers must be greater
  35.                    than .001 or it will cause a stack underflow error
  36.                    to be generated.
  37.              
  38.              STACK UNDERFLOW: The most common cause of this error is
  39.              specifying a roughness value that is too small for your
  40.              computer to handle. It can also be caused by a faulty
  41.              math processor or just math that is too difficult for
  42.              your computer type.
  43.   
  44. OTHER ERRORS: The general philosophy of POV-Ray is that the user knows
  45.               what they want to do and the program shouldn't prevent
  46.               the user from trying any values for parameters. This
  47.               allows the user to do things that were unanticipated by 
  48.               the program's authors and often results in a new and
  49.               exciting way of using the program (like negative colored
  50.               lights) but it can also cause errors like the 
  51.               low roughness\stack underflow error. The program could
  52.               have been made more 'safe', but it would have limited its
  53.               power to do so. Consequently, the program allows freedom
  54.               and allows the freedom to make mistakes.
  55.               
  56.               A good example of this is using height fields as clipping 
  57.               objects (see HFCLIP.POV). This was not supposed to be
  58.               possible, but it sometimes works and can be used to create
  59.               exciting effects. When it doesn't work, though, it aborts 
  60.               the program with a very cryptic error.
  61.               
  62.               So, feel free to experiment outside the bounds of what the
  63.               documentation says is possible, but be aware that this
  64.               could cause errors.
  65.               
  66.  
  67.    
  68. ----------------------------------------------------------------------------  
  69.    Alphabetical List of Errors Generated by POV-Ray 
  70. ----------------------------------------------------------------------------
  71.   
  72. 'X' expected but 'Y' found instead
  73. ----------------------------------
  74. General syntax error. 'Y' was not expected at this place
  75. in the scene file. This often indicates a missing brace.
  76.  
  77. ALPHA colour register value out of range.
  78. -----------------------------------------
  79. The color index given for alpha was outside the range of
  80. color entries for the image's palette.
  81.  
  82. Bad Node type at depth N
  83. ------------------------
  84. Internal data corruption error in Bezier patch code. This error
  85. shouldn't normally occur.
  86.  
  87. Bad default file format.  Offending char: (C), val: D.
  88. ------------------------------------------------------
  89. This error should never occur with the released executables. 
  90. If it does, you may have a corrupted exe file or a virus. 
  91. If the file is not corrupted and a virus is not detected,
  92. please report this problem to the POV-Team.
  93. If you are compiling POV-Ray on your own computer, this
  94. error means that you have changed the default file format
  95. specified in the source to an incorrect value.
  96.  
  97. Bad patch type
  98. --------------
  99. Bezier Patch was not within range (1...4)
  100.  
  101. Can't apply ALPHA to a non colour-mapped image
  102. -----------------------------------------------
  103. A color mapped image is one where the colors used in the
  104. image are stored in a palette. The image data itself is 
  105. a list of numbers referencing that palette. GIF images
  106. are color mapped, as are most IFF images. Targa (TGA) and
  107. dump images are not color mapped, so ALPHA cannot be used
  108. with them.
  109.  
  110. Cannot allocate memory for ...
  111. ------------------------------
  112. This is a general purpose error that can occur in many
  113. places in POV-Ray.  It just means POV-Ray ran out of memory
  114. while trying to build one of the scene's internal data
  115. structures.  Depending on the particular object it was
  116. working on, you may want to increase POV-Ray's memory
  117. allocation, or reduce the size or complexity of the scene.
  118. You can often reduce memory usage easily by removing unecessary
  119. include files, or pasting the needed definitions from the include
  120. file straight into your scene.
  121.  
  122.  
  123. Cannot open GIF file FILE_NAME
  124. ------------------------------
  125. Cannot open IFF file FILE_NAME
  126. ------------------------------
  127. Cannot open Targa file FILE_NAME
  128. --------------------------------
  129. Cannot open dump file FILE_NAME
  130. -------------------------------
  131. Cannot open include file: FILE_NAME
  132. -----------------------------------
  133. Cannot find the file named FILE_NAME in the current directory, 
  134. or in the list of directories specified by the +L command 
  135. line option. Or an error occured while attempting to open 
  136. this file. Make sure the file is in the current directory or 
  137. one of the listed directories and the file name is correctly 
  138. spelled and complete. POV-Ray does not add the extension to 
  139. the file name (.GIF, .TGA, .IFF). It must be specified.
  140.  
  141. Cannot open input file
  142. ----------------------
  143. Cannot find the scene file named by the +i command line option 
  144. in the current directory, or in the list of directories 
  145. specified by the +L command line option. Or an error occured 
  146. while attempting to open this file. Make sure the file is in 
  147. the current directory or one of the listed directories and 
  148. the file name is correctly spelled and complete. POV-Ray does 
  149. not add the extension to the file name (.POV). It must be specified.
  150.  
  151. Colour_Map too long.
  152. --------------------
  153. Color maps may contain no more than MAX_ENTRIES (20) entries
  154.  
  155. Degenerate triangle on line N.  Please remove.
  156. ----------------------------------------------
  157. A 'triangle {}' or a 'smooth_triangle {}' declaration
  158. was found to be invalid on line N of the scene file.
  159. This shape will be ignored and not rendered.
  160.  
  161. Degenerate triangles were found and are being ignored.
  162. ------------------------------------------------------
  163. Some triangle shapes in the scene file were found to be
  164. invalid and are being ignored by the ray tracer. This
  165. message will occur only with triangle {} and smooth_triangle
  166. shapes.
  167.  
  168. ERROR - Containing Index too high
  169. ---------------------------------
  170. MAX_CONTAINING_OBJECTS (10) exceeded.
  171.  
  172. Error - you cannot scale a sphere unevenly
  173. ------------------------------------------
  174. Regular Sphere primitives must be scaled evenly.  To do
  175. uneven scaling, use quadric { Ellipsoid } objects.
  176. EVEN SCALE   = scale <2  2 2>
  177. UNEVEN SCALE = scale <7 .1 3>
  178.  
  179. Error in decimal number
  180. -----------------------
  181. Bad character in number (e.g. 2$3.2 or 89fred0.34 ) This could
  182. indicate a missing space in the scene.
  183.  
  184. Error opening continue trace output file
  185. ----------------------------------------
  186. This error occurs when using the +c command line option.
  187. Cannot find the file specified by the +o command line option
  188. in the current directory, or in the list of directories 
  189. specified by the +L command line option. Or an error occured 
  190. while attempting to open this file. 
  191. Make sure the file is in the current directory or 
  192. one of the listed directories and the file name is correctly 
  193. spelled and complete. POV-Ray does not add the extension to 
  194. the file name (.GIF, .TGA, .IFF). It must be specified.
  195.  
  196.  
  197. Error opening option file FILE_NAME
  198. -----------------------------------
  199. Cannot find the file named FILE_NAME in the current directory, 
  200. or in the list of directories specified by the +L command 
  201. line option. Or an error occured while attempting to open 
  202. this file. Make sure the file is in the current directory or 
  203. one of the listed directories and the file name is correctly 
  204. spelled and complete. POV-Ray does not add the extension to 
  205. the file name (.GIF, .TGA, .IFF). It must be specified.
  206.  
  207. This error can be caused by stray words on the command line.
  208. Any word on the command line that is not preceded by a +/- option
  209. is assumed to be a file containing command line options.
  210.  
  211. Error opening output file
  212. -------------------------
  213. Cannot find the file specified by the +o command line option
  214. in the current directory, or in the list of directories 
  215. specified by the +L command line option. Or an error occured 
  216. while attempting to open this file. 
  217. Make sure the file is in the current directory or 
  218. one of the listed directories and the file name is correctly 
  219. spelled and complete. POV-Ray does not add the extension to 
  220. the file name (.GIF, .TGA, .IFF). It must be specified.
  221.  
  222. Error reading aborted data file
  223. -------------------------------
  224. This error occurs when using the +c command line option.
  225. POV-Ray had an error occur while reading the partial image
  226. output file specified by +o.
  227.  
  228. Expecting a string after INCLUDE
  229. --------------------------------
  230. Syntax for include declaration anticipates a double-quoted
  231. filename string after the word include.
  232. For example: 
  233.     #include "filename.inc" == OK!
  234.     #include  filename.inc  == ERROR
  235.  
  236. Failed to allocate...
  237. ---------------------
  238. This is a general purpose error that can occur in many
  239. places in POV-Ray.  It indicates that POV-Ray ran out of memory
  240. while trying to build one of the scene's internal data
  241. structures.  Depending on the particular object it was
  242. working on, you may want to increase POV-Ray's memory
  243. allocation, or reduce the size or complexity of the scene.
  244.  
  245. GIF Image Map Colour out of range
  246. ---------------------------------
  247. IFF Image Map Colour out of range
  248. ---------------------------------
  249. The color index was outside the image file's palette. This
  250. could indicate a corrupted file.
  251.  
  252.  
  253. Identifier 'X' is the wrong type
  254. --------------------------------
  255. Type mismatch syntax error.  The identifier 'X' is not
  256. the appropriate type of ID for this spot.
  257. This happens if you put a declared color into a quadric, for instance.
  258. For example:
  259.    #declare Red = color red 1
  260.    object { quadric { Red } } // This will cause this error
  261.  
  262. Illegal character in input file, value is XX
  263. --------------------------------------------
  264. Found a bogus half-ASCII character in the source file. These
  265. characters are ignored. It could be a control character left in
  266. by an editing program.
  267.  
  268. Invalid GIF file format: FILE_NAME
  269. ----------------------------------
  270. The file header for FILE_NAME seems not to be a GIF file header. The
  271. file specified may not be a GIF or it could be corrupted.
  272.  
  273.  
  274. Invalid IFF file
  275. ----------------
  276. The file specified may not be an IFF image or it could be corrupted.
  277.  
  278.  
  279. Invalid option: 'OPTSTRING'
  280. ---------------------------
  281. The command line option 'OPTSTRING' is not recognized by POV-Ray.
  282. This could be a mistyped character on the command line, the environment
  283. variable POVRAYOPT, or in an option file specified on the command line.
  284.  
  285. Light source must be defined using new syntax
  286. ---------------------------------------------
  287. The keyword "light_source" was found without the accompanying
  288. light source definition in a place in the file that indicates
  289. it may be an old-style light_source definition.
  290. See POVRAY.DOC for correct light source definition.
  291.  
  292. Need at least one component in a blob
  293. -------------------------------------
  294. There must be at least one sphere element declared in
  295. the blob object.  Declare some components in the blob.
  296.  
  297. Need the order of the Poly
  298. --------------------------
  299. The syntax of poly requires an order be specified
  300. before the <coeffs>
  301.  
  302. No */ closing comment found
  303. ---------------------------
  304. Found a /* (open comment), but no matching */ in the scene file.
  305.  
  306. No colour for value: N
  307. ----------------------
  308. The color map does not define a color for the value N. Make
  309. sure your color map contains entries that completely span the 
  310. range from 0.0 to 1.0.
  311.  
  312. No end quote for string
  313. ------------------------
  314. Hit end of file while reading in quoted string. This indicates a
  315. missing quote (") somewhere.
  316.  
  317. Not enough memory for colour map.
  318. ---------------------------------
  319. See error 'Failed to allocate...'
  320.  
  321. Only NN option file names are allowed in a command line.
  322. --------------------------------------------------------
  323. POV-Ray only allows one 'option file'on the command line. 
  324. MAX_FILE_NAMES (1)
  325.  
  326. Order of Poly is out of range
  327. -----------------------------
  328. The polynomial order must be between 2 and MAX_ORDER (7).
  329.  
  330. Out of Memory. ...
  331. -----------------------------------------------------
  332. See error 'Failed to allocate...'
  333.  
  334. Out of prioqs
  335. -------------
  336. POV-Ray has internally exceeded the NUMBER_OF_PRIOQS (32).
  337.  
  338. Picture index out of range
  339. --------------------------
  340. This error should not occur, but it could occur if your computer
  341. is having floating point math accuracy problems or a corrupted
  342. image file. It indicates that one of the internal mapping routines 
  343. (bump, image, material) tried to get the color of a pixel that was
  344. out of the range of the image. For example, bump_map asked for the
  345. X=321, Y=200 point on a 320 by 200 resolution image.
  346.  
  347. Premature End Of File reading GIF image
  348. ---------------------------------------
  349. POV-Ray found the end-of-file before it expected in a
  350. GIF file. File could be corrupted.
  351.  
  352. String too long
  353. ---------------
  354. No word or number may be longer than MAX_STRING_INDEX (41).
  355. Quoted string (or floating point number) more than
  356. this many characters long found.
  357.  
  358. The order of a polynomial may not be specified twice
  359. ----------------------------------------------------
  360. You can have only one number before the <coeffs>
  361. in a 'poly' decl.
  362.  
  363. Too many constants 'declared'
  364. -----------------------------
  365. The number of declared (#declare) identifiers 
  366. exceeded MAX_CONSTANTS(1000)
  367.  
  368. Too many exits from refractions
  369. -------------------------------
  370. Mismatch between entering and exiting object surfaces, 
  371. could be internal data corruption.
  372.  
  373. Too many library directories specified
  374. --------------------------------------
  375. The number of paths passed on the command line by +L exceeds
  376. MAX_LIBRARIES (10)
  377.  
  378. Too many nested include files
  379. -----------------------------
  380. POV-Ray can't handle more than MAX_INCLUDE_FILES (10) deep. 
  381. A nested include file is an include file in an include file.
  382.  
  383. Too many nested refracting objects
  384. ----------------------------------
  385. MAX_CONTAINING_OBJECTS (10) exceeded. 
  386. This could happen if you place a 15 glass spheres inside of
  387. each other, for example.
  388.  
  389. Too many symbols. Use +ms### option to raise Max_Symbols.
  390. ---------------------------------------------------------
  391. POV-Ray allocates a block of memory for Max_Symbols number of
  392. #declared items. This is normally 500. If this number is too
  393. small, use +ms### to raise the limit of #declared items.
  394. For example:
  395.   povray +ms600 +ifile.pov ...
  396.  
  397. Undeclared identifier 'X'
  398. -------------------------
  399. Tried to use identifier 'X', but it has not yet been defined by
  400. using #declare. This often indicates a spelling error or typo.
  401.  
  402.  
  403. Unexpected end of file
  404. ----------------------
  405. POV-Ray was expecting to get more data and found the end of the file
  406. instead. Often caused by missing brace or quote. 
  407.  
  408. Unrecognized output file format 'X'
  409. -----------------------------------
  410. The file format specified by the +f command line option is 
  411. not one supprted by POV-Ray.
  412. POV-Ray supports the following output file formats:
  413.   D=Dump, I=IFF, R=Raw, T=Targa.
  414.   
  415. pvray +fZ -- Would cause this error
  416.