home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / sipp.lha / sipp / COMPATIBILITY < prev    next >
Text File  |  1993-03-13  |  6KB  |  122 lines
  1.                    Compatibility Guide for SIPP 3.0
  2.                    ================================
  3.  
  4.   To support the new features introduced in version 3.0 of SIPP we had
  5. to drop some backward compatibility.  Most significantly, the
  6. interface to shaders and shader-lightsource interaction has changed
  7. due to added functionality.  Some functions have been replaced by
  8. similar functions with new names and other functions take new
  9. parameters.  How difficult it is to port a program which used an older
  10. version of SIPP (2.x) varies depending on how much of the features in
  11. SIPP the program used.
  12.  
  13.   Some of the incompatibilities can be fixed by just replacing old
  14. function calls with new ones. The include files in the library defines
  15. a number of macros which makes this automatically whenever possible.
  16. The new calls which are produced in this way supply new parameters so
  17. that the call have the same effect as in the previous version. In
  18. the listing of incompatibilities below we have marked all cases where
  19. the include files take care of them with an asterisk "*".  If you
  20. check the list and find only *-marked entries that apply to your
  21. program, a simple recompilation should be enough.  Otherwise the code
  22. must be changed.
  23.  
  24. We strongly suggest that you update your code to the new calling
  25. conventions, even if the macros fix all your problems since the macros
  26. might not be supported in future releases.
  27.  
  28.  
  29. * The internal "database" which contained all objects which should be
  30.   included in a scene has been dropped.  Instead there is a
  31.   "world"-object which should have all objects in a rendering somewhere
  32.   below it in the object hierarchy. 
  33.   Fix needed:
  34.       Change "object_install(foo)" to "object_add_subobj(sipp_world, foo)"
  35.       Change "object_uninstall(foo)" to "object_sub_subobj(sipp_world, foo)"
  36.  
  37.  
  38. * The functions for manipulating the viewpoint has disappeared.  Instead
  39.   there is a predefined camera which is used by default.
  40.   Fix needed:
  41.       Change "view_from(x, y, z)" to "camera_position(sipp_camera, x, y, z)"
  42.       Change "view_at(x, y, z)" to "camera_look_at(sipp_camera, x, y, z)"
  43.       Change "view_up(x, y, z)" to "camera_up(sipp_camera, x, y, z)"
  44.       Change "view_focal(r)" to "camera_focal(sipp_camera, r)"
  45.       Change "viewpoint(x, y, z, x2, y2, z2, ux, uy, uz, r)" to
  46.              camera_params(sipp_camera,x, y, z, x2, y2, z2, ux, uy, uz, r)"
  47.  
  48.  
  49. * The lightsource interface have changed a lot to support new types of 
  50.   lightsources and shadow casting.  Directional lightsources are still
  51.   available though, but a different function is used to create them.  
  52.   Fix needed:
  53.       Change "lightsource_push(x, y, z, i)" to 
  54.              "lightsource_create(x, y, z, i, i, i, LIGHT_DIRECTION)"
  55.  
  56.  
  57. * The function "render_image_pixmap()" is replaced with a new function
  58.   which does the same thing but has a more descriptive name and takes
  59.   its parameters in a more logical order.
  60.   Fix needed:
  61.       Change "render_image_pixmap(w, h, data, function, m, o)" to
  62.              "render_image_func(w, h, function, data, m, o)"
  63.  
  64.  
  65.   The surface descriptions for almost all the included shaders
  66.   (including basic_shader()) have a new entry describing the opacity of
  67.   the surface.  It is stored in a Color structure to allow different
  68.   opacity in the different color bands.  1.0 means a totally opaque
  69.   object while 0.0 means a totally transparent (invisible) one.
  70.   Fix needed:
  71.       Add a definition of opacity whenever a surface description gets
  72.       filled in with values.  Check the manual to see which surface
  73.       descriptions have had this member added.
  74.  
  75.  
  76.   The functions "surface_basic_create()" and "surface_basic_shader()"
  77.   which fills in a Surf_desc indirectly have also got new parameters
  78.   which define opacity.  Unfortunately it is not possible to add
  79.   parameters to a function using a macro, so you will have to fix this
  80.   yourself by hand. 
  81.   Fix needed:
  82.       Add parameters describing opacity to "surface_basic_create()"
  83.       and "surface_basic_shader()".
  84.  
  85.  
  86.   The mask shader is no longer specialized to use an image of some kind
  87.   to mask between two shaders.  It is now much smaller, and more
  88.   general but leaves more work to be done by the user. :-) 
  89.   Fix needed:
  90.       Check the manual to see the new definition of mask_shader() and
  91.       its surface description and change your code to fit it.
  92.  
  93.  
  94.   All functions that create object primitives have a new parameter
  95.   added which defines the kind of texture coordinates that should be
  96.   mapped onto the object.  If your program does not use texture
  97.   coordinates (which includes using a supplied shader that does) and
  98.   you have a forgiving compiler, you can ignore this.  It is probably
  99.   safest to add the new parameter though.
  100.   Fix needed:
  101.       Add a parameter defining texture coordinate system to all object
  102.       functions (sipp_cube(), sipp_cone() etc.).  To get the same
  103.       effect as in previous versions, use the parameter "WORLD".
  104.  
  105.  
  106.   The function that creates surfaces by rotating a bezier curve now
  107.   rotates the curve about the z-axis instead of the y-axis since this
  108.   is more like what most other rendering packages do.
  109.   Fix needed:
  110.       Change any files describing bezier curves. In the vertex list
  111.       you do the following substitutions:
  112.          new y <=> -old z  (Note the negation)
  113.          new z <=> old y
  114.  
  115.  
  116.   Finally, if you have written your own shaders there are quite large
  117.   differences.  We strongly suggest you read the section "Writing your
  118.   own shaders" in the user manual for detailed information of the new
  119.   interface.  Primarily, the shaders take more and different
  120.   parameters and use a special function to evaluate light from
  121.   lightsources. 
  122.