home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / vrml2gl.zip / VRML2GL.DOC < prev   
Text File  |  1997-03-17  |  11KB  |  213 lines
  1. ________________________________________________________________________________
  2.  
  3.                VRML2GL parser for OS/2 2.x, 3.0, 4.0 & WIN32.
  4. ________________________________________________________________________________
  5.  
  6. Version 1.2 (Freeware/Shareware)
  7.  
  8. A programmers tool that convert Virtual Reality Markup Language (VRML) files
  9. to OpenGL source code.
  10.  
  11.  
  12. Written by Leigh McRae.
  13.  
  14. (C) Copyright 1997, Now Enterprises.
  15. All rights reserved.
  16.  
  17. ________________________________________________________________________________
  18.  
  19. INTRODUCTION
  20. ________________________________________________________________________________
  21.  
  22.    VRML2GL was written initially with myself in mind. I was learning how to write 
  23. OpenGL code so I developed a quick no brains tool to generate models from VRML 
  24. meshes. This allowed me to explore many different areas of OpenGL without having
  25. to look worry over models. Along the way I also made a small library of OpenGL
  26. related functions that I have added to this package. This package is Freeware
  27. with an option to regisitered for $20.00. The regisitered version is more 
  28. complete and supported. I might also be able to add some features that regisitered 
  29. users may want as long as the feature doesn't require doing too much major code.
  30.  
  31. ________________________________________________________________________________
  32.  
  33. What does VRML2GL not do?
  34. ________________________________________________________________________________
  35.  
  36.  VRML2GL only does VRML v1.0 files. The following VRML v1.0 nodes (tags) are not 
  37. implemeanted: 
  38.                   AsciiText, FontStyle, Info, LOD, WWWAcnhor and WWWInline. 
  39.  
  40. Also VRML files that have non-simple polygons are supported (undefined results).
  41.  
  42.    ***** Loop building (see below) is only for the registered version. *****
  43.  
  44. NOTE: that these restrictions are reasonable considering this tool was not meant
  45. to create final models. Although the models produced are accurate and reasonably
  46. fast there are many optimization that could be done (see Optimizations). This
  47. tool was made to be paste only two lines of code into yours.
  48. ________________________________________________________________________________
  49.  
  50. What does VRML2GL do?
  51. ________________________________________________________________________________
  52.  
  53.  VRML2GL does all other nodes for VRML v1.0. It is hoped that you will be able 
  54. to simply run the parser and and two lines to you OpenGL code to get the model
  55. up and going. The parse even supports texture mapping. Note that texture mapping
  56. primitives is best as it doesn't require texture coordinates.
  57. ________________________________________________________________________________
  58.  
  59. VRML2GL Configuration FIle                  
  60. ________________________________________________________________________________
  61.  
  62.    VRML2GL uses a configuration file to set some user switches. The file must
  63. be called VRML2GL.cfg. The file is simply a text file that you can edit. The
  64. config file also must be in the working directory. The VRML2gl profile uses 
  65. the same rules as VRML. An explanation of the profile is as follows:
  66.  
  67. FUNC_PREFIX       SFString    # Names functions 'void <SFString>X29( void );'.
  68. FILE_PREFIX       SFString    # Names files '<SFString>X29.c'.
  69.  
  70. SEPARATOR         SFBool      # TRUE -> 'Separator' is unchanged.
  71.                               # FALSE -> 'Separator' = 'SeparatorTransform'.
  72.                               Treat 'Separator' AS 'TransformSeparator'. This
  73.                               was added as I felt that many objects only really
  74.                               need (and maybe mean) to save position. With 
  75.                               'Separator' the parser must save whole meshes and
  76.                               many lists. This is huge over head that cause the
  77.                               parser to slow down and the source code produced 
  78.                               to be slightly larger.
  79.  
  80. LIGHTS_OFF        SFBool      # TRUE -> lights get shut off after 'Separator'.
  81.                               # FALSE -> lights remain on once turned on.
  82. IGNORE_LIGHTS     SFBool      # TRUE -> all light nodes are ignored.
  83.                               # FALSE -> generate lights in the source code.
  84. GL_COLOR          SFBool      # TRUE -> use glColorMaterial(); and glColor3f();.
  85.                               # FALSE -> use regular mglMaterialfv(); calls.
  86. BUILD             SFEnum      # STATIC -> plot commands as received.
  87.                               # LOOP -> use loops and arrays to build objects.
  88.                               Loop or static building of meshes. Have an array
  89.                               of vertices and use a loop to plot the mesh (LOOP)
  90.                               or use many vertex3f(); calls (STATIC). Actually 
  91.                               you can set the parser to both (LOOP only for meshes
  92.                               with more than x vertices).
  93.  
  94. MIN_LOOP          SFLong      # This is the minimum size mesh to LOOP.
  95. PRECISION         SFLong      # Number of digits to the right of the decimal place.
  96.  
  97. AMBIENT           SFBool      # FALSE -> ignore ambient materials.
  98. DIFFUSE           SFBool      # FALSE -> ignore diffuse materials.
  99. SPECULAR          SFBool      # FALSE -> ignore specular materials.
  100. EMISSIVE          SFBool      # FALSE -> ignore emissive materials.
  101. TRANSPARENCY      SFBool      # FALSE -> ignore transparency materials.
  102. SHININESS         SFBool      # FALSE -> ignore shininess materials.
  103.                               Ignore one or more material types. This is useful as
  104.                               I have found that the SHININESS is usually too low.
  105.                               Also if you use glColorMaterial(); and the DIFFUSE
  106.                               is different from AMBIENT then you will get two 
  107.                               glColor3f(); because the parser thinks its a new 
  108.                               color. In order to get around this you can ignore 
  109.                               either DIFFUSE or AMBIENT.
  110.  
  111. ________________________________________________________________________________
  112.  
  113. Example: given a popular VRML file such as X29.WRL
  114. ________________________________________________________________________________
  115.  
  116. vrml2gl x29.wrl
  117.  
  118. Produces:
  119.  
  120. vglObjX29.h             - these are the main source and header files that call
  121. vglObjX29.c               the rest of the source files.
  122.  
  123. vglObjCanard.c           - Note that each function is stand alone. This allows
  124. vglObjCockpit.c           you to extract parts from scenes.
  125. vglObjMfuse.c
  126. vglObjNose.c
  127. vglObjRfuse.c
  128. vglObjVane.c
  129. vglObjVertstab.c
  130. vglObjWings.c
  131.  
  132.  To use the new mesh you include the header file 'vglObjX29.h' and call the
  133. function 'vglDrawX29();'. It is up to the user to set the makefile and make
  134. sure any platform specific includes or defines are set. 
  135. NOTE: you must build the default 'glObjects.c' or supply your own in order
  136. to support drawing of primitives. The functions used are as follows:
  137.  
  138.    void  glObjCube( float width, float height, float depth, int parts );
  139.    void  glObjCylinder( float radius, float height, int parts );
  140.    void  glObjCone( float radius, float height, int parts );
  141.    void  glObjSphere( float radius, int parts );
  142.  
  143. ________________________________________________________________________________
  144.  
  145. Trouble Shooting:
  146. ________________________________________________________________________________
  147.  
  148. 1) Nothing shows up. This is most likely a focus problem. Look on my web page
  149.    for a 'aux' frame work that allows you too try many things out.
  150.  
  151. 2) Source generated is too big and won't compile. See Optimizations.
  152.  
  153. 3) Materials don't seem to work. Some materials won't work for LOOP building
  154.    simply because the code is more trouble than its worth. Use STATIC build.
  155.  
  156. 4) The VRML file might have non-simply polygons.
  157.  
  158. 5) Trace through to see if you have glFrontFace() set right. If this is set too
  159.    GL_CW then you should reset it to GL_CCW when all clockwise meshes are 
  160.    finished.
  161.  
  162. 6) Turn up the shininess factor in the source VRML file. It seems that this is 
  163.    always too low for my taste.
  164.  
  165. 7) Are the Lights on? Use my function in the 'glObj.h' file to set the light 
  166.    positon.
  167.  
  168.    glObjSetLight( 0,                   /* Light number.               */
  169.                   GL_FALSE,            /* Show lamp. Could be better. */
  170.                   GL_TRUE,             /* Is positional.              */
  171.                   0.0, 0.0, 0.0 );     /* Vector position.            */
  172.  
  173. ________________________________________________________________________________
  174.  
  175. Optimizations:
  176. ________________________________________________________________________________
  177.  
  178. 1) Create a display list for the main 'vglDraw' function when your program
  179.    starts up. The just call the display list in your paint routine. The reason
  180.    I chose not to use display lists is because I think it assumes too much. I
  181.    found it to best to brake parts into functions (stand alone functions) and
  182.    let you put the display lists in where you feel. 
  183.  
  184. 2) Remove empty functions. Functions like SceneInfo are usually empty. I guess
  185.    I could have made sure that functions that are empty get parsed but I felt 
  186.    this was overkill (insert cop out here).
  187.  
  188. 3) Play with the MIN_LOOP value. This STATIC to LOOP cut off can really reduce
  189.    code size. Some files over use 'Seperator' for small meshes. Note that the 
  190.    file 'bop.wrl' is responsible for that feature.
  191.  
  192. 4) If the code generate is too big be to compile then you can take the source 
  193.    VRML file and do some find and replaces. Look for any 'Seperator' nodes. For 
  194.    each 'Seperator' node (or the big ones) you want to change them to read
  195.    'DEF x Seperator' where 'x' will be the object name (bop_1, bop_2, bop_3). 
  196.    What this will do is brake the mesh up into different files, as a new source
  197.    file is only create for 'DEF' nodes. This problem is because the object has
  198.    parts that were not named when create (or lost in some conversion).
  199.  
  200. 5) Parse out some of the material that are redundant or not desired.
  201.  
  202. 6) Try and remove some precision using the PRECISION value in the VRML2GL.cfg. 
  203.    Note that this could really ruine the model.
  204.  
  205. 7) Remove some variable declarations that are not used and maybe redo the main
  206.    variable declarations to suit your program.
  207.  
  208. 8) If normal binding is PER_x_INDEXED then change the normal binding to PER_FACE
  209.    too force the parser to generate normals via a function call. This makes the 
  210.    code way smaller but most likely not as nice looking as the original normals 
  211.    provided are for smooth shading.
  212.  
  213.