home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Raytrace & Morphing / SOS-RAYTRACE.ISO / programm / texte / ipas3r.me < prev    next >
Encoding:
Text File  |  1994-04-25  |  10.4 KB  |  292 lines
  1.  
  2.                         Autodesk 3D Studio
  3.                              Release 3
  4.                           IPAS 3 Toolkit
  5.  
  6.                             README.DOC
  7.  
  8.                         February 18, 1994
  9.  
  10.                  Copyright 1994 by Autodesk, Inc.
  11.  
  12.  
  13. 1. GENERAL INFORMATION
  14. ======================
  15.  
  16. WATCOM 9.5 has some known memory allocation problems.
  17. You should upgrade to the b level patch or run the risk of General 
  18. Protection Faults.
  19.  
  20.  
  21. 2. NOTES ON THE DOCUMENTATION
  22. ==============================
  23.  
  24. 2.1 Page 165, pxp_get_item () index Parameter:
  25.  
  26. The first item (index=0) in the drawing database is *always* the 
  27. ambient light.
  28.  
  29. 2.2 Page 125, EXP_AXP_VIEW packet command:
  30.  
  31. EXPbuf->nivfo should read EXPbuf->vinfo.
  32.  
  33. 2.3 Page 34, Col24 Struct:
  34.  
  35. unsigned char r,g,b; should read unsigned int r,g,b;
  36.  
  37. 3. KNOWN TOOLKIT LIMITATIONS
  38. ============================
  39.  
  40. 3.1 Symptom: The gfx_bitmap_info function may return invalid bitmap 
  41. width and height information for some .GIF files not created by 3DS or
  42. Animator Pro, causing subsequent gfx_load_bitmap calls to fail.
  43.  
  44.         Fix: Instead of calling gfx_bitmap_info, call the function 
  45. do_bitmap_info. This detects .GIF file loading and uses proper code to
  46. retrieve the bitmap info.
  47.  
  48. 3.2 Symptom: Flags for mesh objects in the direct-call interface 
  49. (ItemMesh.flags field) are not properly set or returned.
  50.  
  51.         Fix: There is currently no workaround.
  52.  
  53. 3.3 Symptom: The BXP ClientGetFrame (BXP_GET_FRAME packet command) 
  54. mechanism does not work properly. If a BXP is asked to get a 
  55. subsequent frame, even though it returns successfully, 3DS report it 
  56. as a failure.
  57.  
  58.         Fix: There is currently no workaround.
  59.  
  60. 3.4 Symptom: The SXP Client3DOpac function is not getting called by 
  61. 3D Studio. All texture map calls whether opacity, texture, shininess 
  62. are being piped through Client3DText, instead of piping the color ones
  63. thru Client3DText and the monochrome ones thru Client3DOpac.
  64.  
  65.         Fix: There is currently no workaround.
  66.  
  67.  
  68. 4. WATCOM COMPILER-RELATED LIMITATIONS
  69. ======================================
  70.  
  71. 4.1 Symptom: With WATCOM 9.5a the first time you malloc in a 3D Studio 
  72. session, it will fail.
  73.  
  74.         Fix: Try malloc'ing twice before you report a malloc failure.
  75.  
  76. 4.2 Symptom: Iscan.c is unstable with WATCOM 9.5.
  77.  
  78.         Fix: There is currently no workaround.
  79.  
  80.  
  81. 5. DEBUGGING IPAS ROUTINES
  82. ===========================
  83.  
  84. 5.1 Special IPAS Libraries
  85. ==========================
  86.  
  87. A special version of the IPAS libraries is provided to allow debugging
  88. of IPAS routines using various commercially available debuggers like
  89. the ones provided by MetaWare, WATCOM and Phar Lap.  These libraries
  90. differ from the normal libraries in that they execute an INT 3
  91. (debugger trap) upon entering the IPAS routine for the first time.  The
  92. debugger can then use this opportunity to determine the base addresses
  93. of the code and data segments used by the IPAS routine and the
  94. locations of symbols and code therein.
  95.  
  96. Use the debugging libraries in place of the normal libraries during the
  97. linking step of IPAS procedure creation.  The names of the debugging
  98. libraries and the normal libraries they replace are as follows:
  99.  
  100.      XPMW30D.LIB replaces XPMW30.LIB
  101.      XPMW31D.LIB replaces XPMW31.LIB
  102.      XPWC95D.LIB replaces XPWC95.LIB
  103.  
  104. Note: Using these libraries outside the debugging environment will
  105. cause 3D Studio to crash when invoking the IPAS routine linked with
  106. the special library.
  107.  
  108. The batch file (makesamp.bat) provided for building the examples in 
  109. the toolkit will automatically include the special debug library when 
  110. you include the comand line option DEBUG.
  111.  
  112. Because of the graphic user interface of 3D Studio, we recommend that
  113. debugging should only be done in a dual screen or remotely hosted
  114. debugging display.  Refer to the debugger documentation for information
  115. regarding dual screen and remotely hosted debugging.
  116.  
  117. We also recommend that IPAS routines should only be debugged with 3D
  118. Studio's Main, Materials, and Rendering display configured for standard
  119. SVGA.  Refer to the "3D Studio Installation Guide" for more information 
  120. concerning display configuration.
  121.  
  122.  
  123. 5.2 DEBUGGING WITH PHAR LAP 386|DEBUG SYMBOLIC DEBUGGER
  124. =======================================================
  125.  
  126. Prior to debugging the IPAS routine, link the routine with the proper
  127. compiler and linker flags needed by the debugger.  In the case of the
  128. MetaWare 1.73 and 3.0 compilers used in conjunction with Phar Lap's
  129. 386|LINK linker, the compiler option is "-g" and the linker option is
  130. "-SYMBOLS".
  131.  
  132. Start 386|Debug with the following command line:
  133.  
  134.      386debug -symfile [IPAS] 3ds.exe
  135.  
  136. In the above example, [IPAS] represents the name of the IPAS routine
  137. being debugged.  The -symfile switch tells 386|DEBUG to use the symbol
  138. file contained within the [IPAS] executable.
  139.  
  140. Start 3DS from the 386|DEBUG '-' prompt with the g (go) command.  Then
  141. execute the IPAS routine from within 3DS. When the IPAS routine is
  142. executed, control will return back to 386|DEBUG prompt along with a
  143. display of the processor's registers.  To get past the INT 3 breakpoint
  144. and enter the application, use the following command:
  145.  
  146.      r eip eip+1
  147.  
  148. Use the debugger's xr command to relocate the segment selector values
  149. so they are relative to the application (rather than to the 3DS
  150. executable).  This command has the form of:
  151.  
  152.      xr oldsel newsel
  153.  
  154. Where oldsel is the original selector value, and newsel is the new
  155. value used by the IPAS routine.  You can find out what the current
  156. selector values are by using the debugger's xs command.  Once you know
  157. the current settings, you can replace them with the settings displayed
  158. in the CS and DS registers.  For example, the xs command reveals that
  159. the CODE selector is C and the DATA selector is 14, and the register
  160. display shows that CS is now 5C and DS is now 54 for the IPAS routine.
  161. Use the following commands to change the selectors:
  162.  
  163.      xr C 5C
  164.      xr 14 54
  165.  
  166. To set a breakpoint in the application, you can use the bp command.
  167. For example, to set a breakpoint at the beginning of the ClientStartup
  168. function enter the following:
  169.  
  170.      bp ClientStartup
  171.  
  172. You can use the g command to reenter the IPAS routine.
  173.  
  174.  
  175. 5.3 DEBUGGING WITH THE METAWARE DEBUGGER (MDB.EXE)
  176. ==================================================
  177.  
  178. Prior to debugging the IPAS routine, link the routine with the proper
  179. compiler and linker flags needed by the debugger.  In the case of the
  180. MetaWare 1.73 and 3.0 compilers used in conjunction with Phar Lap's
  181. 386|LINK linker, the compiler option is "-g" and the linker option is
  182. "-CVSYMBOLS".
  183.  
  184. Start the debugger with the following command:
  185.  
  186.      mdb
  187.  
  188. After starting the debugger, load 3D Studio with the following command:
  189.  
  190.      load "3DS.EXE"
  191.  
  192. You can then start 3DS with the "go" command.  When the IPAS routine is
  193. executed, control will return to the debugger.  To skip past the INT 3
  194. instruction, increment the eip register by 1 using the following
  195. command:
  196.  
  197.      eip++
  198.  
  199. Load the symbol information for the IPAS routine with the following
  200. debugger command:
  201.  
  202.      load "[IPAS]" nocode
  203.  
  204. In the above example, [IPAS] represents the name of the IPAS routine
  205. being debugged.  The "nocode" option tells the debugger to only load
  206. the symbol information for the IPAS routine, not the routine itself.
  207.  
  208. At this point, the location of the source code should be set in the
  209. debugger's configuration.  Various breakpoints and watchpoints can be
  210. defined as well.  For more information regarding this, refer to the
  211. MetaWare documentation.
  212.  
  213.  
  214. 5.4 REMOTE DEBUGGING WITH THE METAWARE DEBUGGER
  215. ===============================================
  216.  
  217. Prior to debugging the IPAS routine, link the routine with the proper
  218. compiler and linker flags needed by the debugger.  In the case of the
  219. MetaWare 1.73 and 3.0 compilers used in conjunction with Phar Lap's
  220. 386|LINK linker, the compiler option is "-g" and the linker option is
  221. "-CVSYMBOLS".
  222.  
  223. Before attempting to operate the debugger remotely, please read the
  224. remote debugging section in the MetaWare documentation.  This
  225. section's intention is to add to that information, not replace it.  For
  226. the sake of clarity, the system used to execute 3D Studio shall be
  227. referred to as the monitor system, and the system used to execute the
  228. MetaWare Debugger shall be referred to as the remote system.
  229.  
  230. The following files, necessary for remote operation, can be found in
  231. the MetaWare compiler's BIN directory:
  232.  
  233.      MDB.CNF
  234.      MDB.EXE
  235.      MDB.TXT
  236.      MDB.BOD
  237.      MDB.IDX
  238.      MDB1.EXP
  239.      DBGLIB.REX
  240.      MDB.ENV
  241.  
  242. and in the Phar Lap BIN directory:
  243.  
  244.      RUN386.EXE
  245.  
  246. Copy these files into a directory on the remote system.  The directory
  247. should be listed in the remote system's PATH setting.
  248.  
  249. Edit the MDB.ENV text file on the remote system so that it contains the
  250. correct PORT and BAUD settings to reflect the COM Port and Baud Rate
  251. being used for remote debugging.  Refer to the MetaWare documentation
  252. for more information about these settings.
  253.  
  254. The following files, necessary for monitor operation, can be found in
  255. the MetaWare compiler's BIN directory:
  256.  
  257.      MON.EXP
  258.      DBGLIB.REX
  259.  
  260. and in the Phar Lap BIN directory:
  261.  
  262.      RUN386.EXE
  263.  
  264. Copy these files into a directory on the monitor system.  The directory
  265. should be listed in the monitor system's path.
  266.  
  267. Create a directory on the remote system with the same name as the 
  268. 3D Studio directory  located on the monitor system.  Into this 
  269. directory, copy the 3DS.EXE program file, the IPAS routine being 
  270. debugged, and the source code to the IPAS routine (if you wish to do 
  271. source level debugging).
  272.  
  273. Copy to the monitor system the IPAS routine being debugged into the
  274. directory containing 3D Studio.
  275.  
  276. Start the monitor program.  The command to do this is:
  277.  
  278. run386 mon [COM #] [SPEED]
  279.  
  280. Where [COM #] is the number of the COM port, either 1 or 2, and [SPEED]
  281. is the baud rate.  Note that the COM port used on the monitor may or
  282. may not be the same as the one used on the remote system.  Refer to the
  283. MetaWare documentation for more information regarding the use of the
  284. monitor program.
  285.  
  286. On the remote system, continue with the instructions discussed in the
  287. prior section entitled "Debugging with the MetaWare Debugger (MDB.EXE)"
  288. beginning with the paragraph "Start the debugger with the following 
  289. command:."
  290.  
  291.                              [END]
  292.