home *** CD-ROM | disk | FTP | other *** search
/ Hack-Mag 2 / Hack-Mag - Issue 2 (1990-11-23)(D-Tect)(PD).adf / Tools / ConSculpt.LZH / ConvS.doc < prev    next >
Encoding:
Text File  |  1990-09-04  |  10.4 KB  |  294 lines
  1. *************************************************************************
  2. *                                                                       *
  3. *   AMICOM'S SCULPT TO SOURCE CONVERTER   CONS V1.29 (1989-11-29)       *
  4. *                                                                       *
  5. *************************************************************************
  6.  
  7.  
  8.        ConS V1.29 Description
  9. ---------------------------------
  10.  
  11. Cons converts Sculpt objects (.scene files) to assembler source code.
  12. It also allows you to produce C or other languages.
  13. It deals primarily with edges, a simple face converter is also available.
  14. Two output formats for edges are available: standard point-to-point
  15. and AMICOM format#2, designed for ultra fast line draw.
  16.  
  17.  
  18.  
  19.        ConS V1.29 Instructions
  20. ---------------------------------
  21.  
  22. AMICOM'S Sculpt Converter V1.29 (1989-11-29)
  23. Usage: file [-DIV n] [-CFORMAT=CF s] [-FFORMAT=FF s] [-FACE]
  24.        [-EFCR] [-EFAMICOM=EFA] [-ITEMS n] [-ECMULT=ECM n]
  25.  
  26.  Input and output file
  27. -----------------------
  28. To convert a file, specify the name of the source file only.
  29. The converted data is sent to the standard output (e.g to the CLI
  30. window, if not specified). Use CLI output redirection to get a file.
  31.  
  32. Example: You have a Sculpt (TM) data file named 'test.scene' and want to
  33.          convert it into a file called 'test.asm'.
  34.          Then you should enter
  35.  
  36.          ConS >test.asm test.scene [options]
  37.               ^         ^
  38.         redirection    argument(s)
  39.  
  40.  
  41.  ConS options
  42. --------------
  43. The converter has been designed in a way to give the user a maximum of
  44. flexibility concerning the output format. Although it has been primarily
  45. designed for assembler users, it allows you to produce data files for
  46. almost all kinds of programming languages.
  47.  
  48. ConS uses options in UNIX syntax. An option is preceeded by a '-' (minus)
  49. mark. You need not bother for upper/lower case.
  50.  
  51.  
  52. ----------------------------------------------------------------------
  53. Option FACE
  54. Use this option to get a listing of faces, too.
  55. Each face is described by a list of all its edge points followed by a
  56. termination code. The default termination code is 'dc.w -1'.
  57.  
  58.  
  59. ----------------------------------------------------------------------
  60. Option DIV number
  61. This option lets you determinate the numerical range for the coordinates
  62. list. It also sets the format of coordinates to words.
  63. (instead of longwords)
  64. Without this option, the coordinate values are taken from the source
  65. data 'as is'. They are longwords and may range from -100,000 to +100,000
  66. or even more.
  67. If you use this option, the source values are divided by the value you
  68. give. The result must be a word (e.g range from -32768 to +32767).
  69. If it exceeds word boundaries, an error is reported.
  70.  
  71. Example: You generated a Sphere by selecting 'ADD SPHERE' and want to
  72.          convert it to have a radius of 1000. The radius of the Sculpt
  73.          sphere usually is 75,000. Therefore you should enter
  74.  
  75.          ConS sphere.scene -div 75
  76.  
  77. ----------------------------------------------------------------------
  78. Option CFORMAT = CF string
  79. ! This is an option for the advanced user. You need to have some knowledge
  80. ! about C-syntax and namely format strings to be able to make use of it.
  81. This option allows you to set the format string for the coordinates
  82. readout. The default string used is - depending upon whether or not you
  83. used option DIV - 
  84.  
  85.    " dc.l    $%08lx,$%08lx,$%08lx\n"    without DIV
  86.    " dc.w    %6d,%6d,%6d\n"             with    DIV
  87.  
  88. To be able to use this option correctly and get a maximum of utility out
  89. of it you should keep in mind the following:
  90.  
  91. - place the string within quotation marks, to allow for space or tab
  92. - in case you want to have a special character inside it, here is a
  93.   list of supported translations
  94.  
  95.   \n  means newline    = $0a = CR
  96.   \t  means tab        = $09
  97.   \0  means endString  = $00 = CTRL-@
  98.   \s  means dollar           = '$'  ( non-standard!)
  99.  
  100. Warning: Users of ARP-Shell or old CLI should ALWAYS use \s instead of $.
  101.          The ARP-Shell gets confused by the misuse of $ 
  102.          Also, you MUST use the real quotation mark (") around
  103.          all texts that contain a semicolon (;). Otherwise, the Shell
  104.          assumes this character terminates the input string.
  105.  
  106.  
  107. EXAMPLE: Let's say you want to use Sculpt data in a BASIC program.
  108.          Therefore, you may wish to provide 'DATA' statements and
  109.          a convenient number format.
  110.          In this case, you might set the coords formatting string to
  111.          something like in
  112.  
  113.          Cons object2.scene -CF 'DATA   &H%08lx,&H%08lx,&H%08lx \n'
  114.  
  115.          This gives you the preamble &H for hexadecimal in BASIC
  116.          instead of $ in Assembler.
  117.  
  118.  
  119. ----------------------------------------------------------------------
  120. Option FFORMAT = FF string
  121. ! This is an option for the advanced user.
  122. ! Also refer to option CFORMAT for general introduction.
  123. It alows you to specify up to 4 format strings for the edge and face
  124. readouts. The default strings are:
  125.  
  126.  
  127.      " dc.w\t"
  128.      "%ld,"
  129.      "\t;\n"
  130.      "\t;\n dc.w    -1\n",0
  131.  
  132. The 1st one is used for edges and faces everytime a new line containing
  133. a list of numbers starts.
  134.  
  135. The 2nd one is used for edges and faces as number format descriptor.
  136.  
  137. The 3rd one is used for edges only, to terminate a line.
  138.  
  139. The 4th one is used for faces only, to provide a 'end of face' control
  140. character and start a new line.
  141.  
  142. HOW TO ENTER MULTIPLE STRINGS:
  143. You start a second string by terminating the first one with a CTRL-@.
  144. Use \0 to get an end-string character.
  145. You can change all strings, or only the ones you want. Simply give
  146. a nul string for the string you want to remain unchanged.
  147.  
  148.  
  149. EXAMPLE: Let's say you want to change the dc.w statement and the colon
  150.          at the end of each line in the edges readout.
  151.          This will do it for you:
  152.  
  153.          ConS file -FF 'DATA \0\0 :REM remark\n'
  154.                         ^    ^   ^
  155.                         |    |   start of 3rd string
  156.                         |    skip 2nd string
  157.                         1st string
  158.  
  159. Please note that no specification for the 4th string has been made
  160. at all. You need not enter a nul-string for following string entries,
  161. but only for those you want to skip.
  162.  
  163.  
  164. EXAMPLE 2: To change only the face-termination string write:
  165.  
  166.          ConS file -FACE -FF '\0\0\0\n---END---\n'
  167.  
  168. ----------------------------------------------------------------------
  169. Option EFAMICOM = EFA
  170.  
  171. This option selects a special output format for the edges (lines).
  172. The default system is: define a line by its start- and ending point nr.
  173. The AMICOM system is: Hold a fix starting point (begin with number 0),
  174. then interpret all incomming point numbers as ending points of lines
  175. to the held starting point. Continue until a control code comes in:
  176. Negative numbers are control codes. -1 means 'increment starting point
  177. number', -2 means 'increment starting point number by 2', and so on.
  178. All point numbers and control codes are multiplied by a factor adjustable
  179. usig option ECMULT. The default multiplication factor is 8.
  180. A special end code is represented by the hex value $80fe.
  181.  
  182. ----------------------------------------------------------------------
  183. Option ECMULT=ECM number
  184.  
  185. This option is used for the AMICOM edges format.
  186. It sets the multiplication factor for point numbers and skip-points
  187. control codes. The default value is 8.
  188. This option can also be used for the normal format. Here, the
  189. default value is 1.
  190.  
  191. ----------------------------------------------------------------------
  192. Option EFCR
  193.  
  194. This option slightly changes the the AMICOM format:
  195. With this option set, a new line is forced after every control code.
  196.  
  197. ----------------------------------------------------------------------
  198. Option ITEMS number
  199.  
  200. !! ATTENTION: This option is marked 'ITEM' in the internal usage note. !!
  201. Lets you choose the number of values displayed per line.
  202. Gets applied for edges and faces.
  203.  
  204. ----------------------------------------------------------------------
  205.  
  206.  
  207.  
  208.       ConS V1.29 Error messages
  209. -------------------------------------
  210. *** Input line too long!
  211.     -
  212.  
  213. *** Error in numerical.
  214.     Invalid numerical parameter to an option.
  215.  
  216. *** Missing string parameter
  217.     An option you used needs a string parameter.
  218.  
  219. *** Got unexpected argument. Specify only input file name.
  220.     Check for '-' before options.
  221.  
  222. *** Missing input file name.
  223.     -
  224.  
  225. *** Unrecognized option '%s'
  226.     Options are: DIV,CF,FF,FACE,EFCR,EFA,ITEM,ECM
  227.     !! Note that option ITEMS is marked as just 'ITEM' - sorry, an error !!
  228.  
  229. *** Invalid input file <name>!
  230.     The file is not a sculpt file.
  231.  
  232. *** Input file too short or corrupt.
  233.     -
  234.  
  235. *** Can't open <file> - DOS error <nr>
  236.     -
  237.  
  238. *** Can't get memory (<nr> bytes) for source file!
  239.  
  240. *** No VERT (coords) chunk found - Operation aborted.
  241.     Something wrong with the sculpt file.
  242.  
  243. *** No EDGE (lines) chunk found - Operation aborted.
  244.     -
  245.  
  246. *** No FACE chunk found - Operation aborted.
  247.     -
  248.  
  249. *** User break.
  250.     Can be forced by ^C, ^D
  251.  
  252. *** Value in coords list exceeds word bounds! Operation aborted.
  253.     Option DIV must be given a larger parameter.
  254.  
  255.  
  256.  
  257.  
  258.   APPENDIX: The formatstring syntax.
  259. ---------------------------------------
  260. Format strings are used to display variable data elements within
  261. a fix context. The format string describes what data type you want
  262. to diplay and allows you to specify exactly how to display it.
  263. A format sequence may be used anywhere within a string and is
  264. replaced by the text it describes.
  265.  
  266. In the C language, formatted text output is a vital element and is
  267. automatically performed by the printf routine.
  268.  
  269. In Assembler, you can use format strings with all data types except
  270. floating point numbers using the exec.library routine RawDoFmt.
  271.  
  272. A format string looks like this
  273.            %   [-] [0]   [number[.number]]    [s|x|lx|d|ld]
  274.           (1)  (2) (3)   (4)                  (5)
  275.  
  276. where (1) is the control character to introduce a format sequence
  277.       (2) a preceding - means 'print left-bounded'
  278.       (3) a preceeding 0 means 'display trailing zeros' (numbers only)
  279.       (4) if you don't specify a number, then whatever you display
  280.           will appear in its true length
  281.           If you specify one number N (may be one ore more digits)
  282.           then the text will use AT LEAST N chars, padded if necessary
  283.           with SPACEs.
  284.           If you specify a second number after the point like N.M
  285.           then the text will use at least N and to the most M chars.
  286.       (5) the actual data type descriptor
  287.            s = string
  288.            x = hex (word)    lx = hex (longword)
  289.            d = dec (word)    ld = dec (long)
  290.            f = floating point (not supported)
  291.  
  292.  
  293.  
  294.