home *** CD-ROM | disk | FTP | other *** search
/ Virtual Reality Homebrewer's Handbook / vr.iso / vr386 / renderer.h < prev    next >
C/C++ Source or Header  |  1996-03-19  |  10KB  |  242 lines
  1. // RENDERER CORE INCLUDES AND DEFINES
  2. // 26/12/93 by Dave Stampe
  3. // All algorithms and code (c) 1993, 1994 by Dave Stampe
  4.  
  5. /*
  6.  This code is part of the VR-386 project, created by Dave Stampe.
  7.  VR-386 is a desendent of REND386, created by Dave Stampe and
  8.  Bernie Roehl.  Almost all the code has been rewritten by Dave
  9.  Stampre for VR-386.
  10.  
  11.  Copyright (c) 1994 by Dave Stampe:
  12.  May be freely used to write software for release into the public domain
  13.  or for educational use; all commercial endeavours MUST contact Dave Stampe
  14.  (dstampe@psych.toronto.edu) for permission to incorporate any part of
  15.  this software or source code into their products!  Usually there is no
  16.  charge for under 50-100 items for low-cost or shareware products, and terms
  17.  are reasonable.  Any royalties are used for development, so equipment is
  18.  often acceptable payment.
  19.  
  20.  ATTRIBUTION:  If you use any part of this source code or the libraries
  21.  in your projects, you must give attribution to VR-386 and Dave Stampe,
  22.  and any other authors in your documentation, source code, and at startup
  23.  of your program.  Let's keep the freeware ball rolling!
  24.  
  25.  DEVELOPMENT: VR-386 is a effort to develop the process started by
  26.  REND386, improving programmer access by rewriting the code and supplying
  27.  a standard API.  If you write improvements, add new functions rather
  28.  than rewriting current functions.  This will make it possible to
  29.  include you improved code in the next API release.  YOU can help advance
  30.  VR-386.  Comments on the API are welcome.
  31.  
  32.  CONTACT: dstampe@psych.toronto.edu
  33. */
  34.  
  35.  
  36.  
  37. #include "vr_ctypes.h"
  38.  
  39. // This file is the best documentation for the renderer
  40. // and how to use it.  To use the renderer, you will need
  41. // graphics routines as defined in F3DKITD.H, a stub for
  42. // accessptr(), the INTMATH library, and some user callback
  43. // routines described below. These are: (read more below):
  44.  
  45. // accessptr(void *) : allows MAP-EMM system to make memory accessible
  46.  
  47. // void user_render_poly(WORD vertex_count, WORD *pcoords,
  48. //             SURFACE poly_color, COORD max_depth);
  49.  
  50. // unsigned user_poly_color(POLY *p, unsigned pcolor,
  51. //            unsigned nppoints, long maxz);
  52.  
  53. // void user_setup_blitter();
  54. // void user_reset_blitter();
  55.  
  56. // if in doubt, look through RENDCODE.C
  57.  
  58.  
  59.  
  60. /************* VIEWPORT CONTROL ************/
  61.  
  62.  
  63.     /* fetches the viewpoint position, even if set by matrix */
  64. extern void real_viewpoint(VIEW *v, long *x, long *y, long *z);
  65.  
  66.     /* compute eye point/ angle movement factors only     */
  67.     /* uses the pan/tilt/roll/x/y/z data in viewport      */
  68.     /* use if view position has changed, but nothing else */
  69.     /* still need to call render_set_view afterwards      */
  70. extern void fast_view_factors(VIEW *v);
  71.  
  72.     /* 100% compatible with original REND386 viewport call */
  73.     /* don't use for new code  (bit of a waste of time)    */
  74. extern void compute_view_factors(VIEW *v);
  75.  
  76.     // sets the view point/angle from a matrix.  This
  77.     // is the only way to go for real VR work!
  78.     // still need to call render_set_view afterwards
  79. extern void matrix_view_factors(VIEW *v,MATRIX m);
  80.  
  81.     // extract a matrix from the view.  Should not be needed
  82.     // if you're just using matrices to move viewpoint, but
  83.     // might be useful if the viewport is on the end of a lot
  84.     // of transforms (i.e stereoscopic)
  85. extern void view_to_matrix(VIEW *v,MATRIX m);
  86.  
  87. /************ MEMORY AND RENDERER SETUP ************/
  88.  
  89. #define MAXVERTICES 20    // polys should have no more than 20 vertices
  90.  
  91. extern void *vtxram;          /* memory allocation area start */
  92.  
  93.     // releases renderer resources.  Already done at exit
  94. extern void reset_render();
  95.  
  96.     // initializes renderer, also initializes integer math library
  97.     // allocates <mem> K of memory: up to 63K for poly and vertex
  98.     // working copies, which limits numbers visible on screen.
  99.     // <polys> determines how many polys or objects can be seen:
  100.     // use about 3000
  101.     // between renders, this memory can be re-used for trmporaries
  102.     // by use of vtxram.  Be careful!
  103. extern void *setup_render(unsigned mem, int polys);
  104.  
  105.  
  106. /******** DRAWING CLIPPED POLYS ***********/
  107.  
  108.     // Some routines (i.e the horizon drawing) need a way to
  109.     // draw XY clipped polys through the renderer.  This routine
  110.     // accepts arrays of X and Y screen coordinates (+/-32000 range)
  111.     // then clips and draws them immediately.  No depth sorting, and
  112.     // the color is passed directly to user_render_poly
  113. extern void render_ext_poly(int npoints, int vx[20], int vy[20], unsigned color);
  114.  
  115. /********** SCREEN-POINT MONITOR ***********/
  116.  
  117. // these routines control/read a monitor which looks at the polys
  118. // going out during rendering to see where in the world a screen point is.
  119. // because the renderer can be called many times to draw a world divided
  120. // by splits, the monitor records across render calls.
  121.  
  122.     // turns the monitor on, and clears it
  123.     // sets the screen point to be tested
  124. extern void set_screen_monitor(int x, int y);
  125.  
  126.     // turns off the monitor.
  127.     // data may still be read out later.
  128. extern void clear_screen_monitor();
  129.  
  130.     // returns the object that was visible at the point
  131.     // returns NULL if no object was found
  132. extern OBJECT *screen_monitor_object();
  133.  
  134.     // returns pointer to poly that was visible at the point
  135.     // returns NULL if no poly was found.
  136. extern POLY *screen_monitor_poly();
  137.  
  138.     // returns vertex number of poly that was closest (within 50 pixels)
  139.     // of the test point.  This is NOT the vertex number in the object!
  140.     // if no vertex was close enough, -1 is returned
  141. extern int screen_monitor_vertex();
  142.  
  143.  
  144. /************* DRAWING POLYS *************/
  145.  
  146.     // YOU must supply this routine, to draw the polys given
  147.     // the vertices and color.  Simple, really.  The poly_color was
  148.     // supplied by user_poly_color(), another of your routines.
  149.     // So these two can do a lot of work together.
  150. extern void user_render_poly(WORD vertex_count, WORD *pcoords,
  151.                  SURFACE poly_color, COORD max_depth);
  152.  
  153. /*********** COLOR AND LIGHTING SUPPORT ***********/
  154.  
  155.     // YOU must supply this routine!
  156.     // the renderer will call this routine to get the color
  157.     // the poly is to be drawn in.  You have the poly (to be passed
  158.     // to compute_poly_cosine() if desired), the number of points
  159.     // (1 if dot, 2 if line, >2 if poly) and the maximum depth of
  160.     // the poly (for depth lighting).
  161.     // You are given the poly's color field in <pcolor>, which
  162.     // you must translate into a color that your poly drawing
  163.     // routine user_render_poly() can handle.  See COLORMAP.C
  164.     // for an example.  These callbacks make it easier to upgrade
  165.     // the renderer to do new things in the future.
  166. extern unsigned user_poly_color(POLY *p, unsigned pcolor,
  167.                 unsigned nppoints, long maxz);
  168.  
  169.     // given poly, computes its cosine*127 from its first
  170.     // vertex to the given (light) point.  Used for lighting,
  171.     // may be used by the color callback routine above.
  172.     // if vect is set, the <xyz> point is a directional vector
  173.     // of the light (spotlight), else it is the position of
  174.     // the light source itself
  175. extern int compute_poly_cosine(POLY *p, long x, long y, long z, int vect);
  176.  
  177.  
  178. /******* OBJECT REPRESENTATION UPDATE CALLBACK ********/
  179.  
  180.     // sets up routine to be called when an object's
  181.     // representation is to be displayed that needs updating
  182.     // usually used to move representations to match object
  183.     // called when the object's and representation's update_count field
  184.     // do not match.  This could happen if the object is moved, which
  185.     // increments its update_count.  Then when the object is drawn,
  186.     // the representation must be moved to match.  You can increment
  187.     // the representation's count too, or leave it to be called every
  188.     // time the object is visible.
  189. extern void *set_renderer_update_handler(void (*handler)(OBJECT *o) );
  190.  
  191.  
  192.  
  193. /*************** OBJECT LIST RENDERING *************/
  194. // at last! something high-level!
  195.  
  196.     // these two are YOUR routines, called before and after a burst
  197.     // of rendering in case you need to set up/reset video hardware.
  198.     // VGA drivers should call setup_hdwe(0) and reset_hdwe() for
  199.     // these respectively.
  200. extern void user_setup_blitter();
  201. extern void user_reset_blitter();
  202.  
  203.     // render an objectlist.  The renderer will call
  204.     // user_setup_blitter(), then process and sort the
  205.     // objects.  Finally, the polys will be blasted out to
  206.     // user_render_poly() to be drawn.
  207.     // You must call render_set_view before this, but you
  208.     // can draw bunches of object lists with repeated calls
  209.     // (say, for a world divided by splits)
  210. extern void subrender(OBJLIST *objlist);
  211.  
  212.     // this is a little more expensive, but calls the
  213.     // wiewport setup itself.  Good if all you'll draw
  214.     // is one objectlist.  The code for it is shown below:
  215. extern void render(OBJLIST *objlist, VIEW *view);
  216.  
  217. //  void render(OBJLIST *objlist, VIEW *view)
  218. //    {
  219. //      render_set_view(view);
  220. //      subrender(objlist);
  221. //    }
  222.  
  223. /************* VIEWPORT SETUP AND INITIALIZE *********/
  224.  
  225. // viewport must have been processed by
  226. // initialize_screen_factors() in the past,
  227. // and then viewpoint can be changed with
  228. // fast_view_factors() or matrix_view_factors
  229.  
  230.     /* copy viewport data to fast access area */
  231.     /* to prepare renderer to draw a view     */
  232.     /* do after viewpoint or look angle has changed */
  233. extern void render_set_view(VIEW *v);
  234.  
  235.     /* compute screen and viewport factors.  These stay constant   */
  236.     /* over eye point changes.  Call this to initialize a viewport */
  237.     /* and after the view parameters such as zoom or stereo change */
  238. extern void initialize_screen_factors(VIEW *v);
  239.  
  240.  
  241.  
  242.