home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 505b.lha / Ham_e_library / renderlib.doc < prev    next >
Text File  |  1991-05-05  |  10KB  |  214 lines
  1.       =----------------------------------------------------------=
  2.       |                   renderhame.library                     |
  3.       =----------------------------------------------------------=
  4.       
  5.       Provides high quality rendering "in a can" for applications
  6.              needing to write HAM-E format images.
  7.  
  8.       ------------------------------------------------------------
  9.      Last updated for version 1.0  --------------- April 19th, 1991
  10.       ------------------------------------------------------------
  11.  
  12. Copyright Notice:
  13. =================
  14. "renderhame.library" is Copyright 1991 Black Belt Systems, ALL RIGHTS
  15. RESERVED under the Pan-American conventions.
  16.  
  17. Disclaimer and Agreement for Use:
  18. =================================
  19. This software is provided as is. Black Belt Systems takes no
  20. responsibility for data manipulated with this software; or for the
  21. interpretation of such data. The user is entirely responsible for the
  22. interpretation and use of image data manipulated with the
  23. renderhame.library software and the HAM-E. The user is also responsible
  24. for observing the Copyright restrictions on materials manipulated with
  25. the renderhame.library. Black Belt Systems will make solid efforts to
  26. maintain this library in a reliable, bug-free form, but cannot be held
  27. responsible if problems with the software incur losses of any type upon
  28. the user. The user is responsible for reporting bugs to Black Belt
  29. Systems. If these terms and conditions are not acceptable to the user,
  30. then Black Belt Systems declines to issue permission to the user to use
  31. renderhame.library in any manner for any purpose whatsoever.
  32.  
  33. Renderhame.library software project credits:
  34. ============================================
  35.  
  36. Programming
  37. -----------
  38. Pete Patterson --- Library implementation, conversion of all routines
  39.                    used to reentrant code methods, recoding of most of
  40.                    the IFF saver.
  41.                    
  42. Ben Williams ----- Spectral color render code and methods, 24 bit color
  43.                    space methods for EDD dither and Hi-Q ham-e render.
  44.                    
  45. Tom Krehbiel ----- Hi-Q 18 bit ham-e mode render code.
  46.  
  47. Matt Dillon ------ Original PD code that the IFF saver was derived from.
  48.  
  49. Documentation
  50. -------------
  51. Pete Patterson, Ben Williams
  52.  
  53. Funding
  54. -------
  55. Black Belt Systems - Support for the HAM-E project.
  56.  
  57. Introduction
  58. ============
  59. This library provides three functions which were not included in the
  60. hame.library because they are fundamentally different from low-level
  61. hame code. Two of these functions provide HAM-E mode and REG mode
  62. rendering routines while the third provides a basic IFF file save
  63. function. The library must be present in the libs: directory on any
  64. system wishing to use these functions.
  65.  
  66. It is important to note that all of these routines require that
  67. the hame.library also be present, and that it is not possible to use
  68. these routines without also using the hame.library.
  69.  
  70. In addition to the structures defined and used in hame.library, there is
  71. one additional structure that is defined for use by the render.library.
  72.  
  73. Here is the definition of the rgb_image structure used by the rendering
  74. routines:
  75.  
  76.   struct rgb_image
  77.     {
  78.       /* User portion */
  79.       int xsize, ysize;                  /* fill these in before using*/
  80.       unsigned char *rbu, *bbu, *gbu;    /* fill in these too */
  81.  
  82.       /* Private portion */
  83.       int              last_reg;          /* leave all of the rest alone */
  84.       short           *ooxmap, *ooymap;
  85.       UBYTE           *CubeLookup;
  86.       UBYTE            Palette24[(3*256)+4];
  87.       unsigned char    reg_mem[256][3];
  88.       unsigned char    reg_memx[256][3];
  89.       unsigned short  *cspace;
  90.       struct HamePort *HamePort;
  91.       int              u_r_here;
  92.     };
  93.  
  94. Please note that the only variables we sanction the use of within the
  95. rgb_struct are the xsize, ysize, rbu, gbu and bbu parameters. The rest
  96. of the variables are private data used by the rendering routines.
  97.  
  98. To use either of the rendering routines, you must fill in the first
  99. five members of the rgb_image structure. The xsize and ysize members
  100. indicate the width and height of the image represented by the RGB data.
  101. The rbu, gbu and bbu members are pointers to the red, green and blue
  102. data buffers. These buffers do not need to be in CHIP ram, and in fact
  103. performance will be adversely affected if they are in CHIP ram.
  104.  
  105. The data in the red, green and blue buffers consists of single bytes,
  106. each of which is interpreted as an unsigned color component value. 
  107. Color component values range from 0-255 and when three of them are
  108. taken together a 24 bit color number is obtained.
  109.  
  110. The data itself should be organized in row,column order. That is, if
  111. the data is scanned in order from the start address toward increasing
  112. addresses, the data should represent the first row of data from left to
  113. right, followed by the second row of data from left to right etc.  The
  114. total amount of data should be equal to the xsize times the ysize.
  115.  
  116. Once your data is in your buffers and your rgb_image structure is
  117. initialized, you need to get a HamePort pointer upon which to render
  118. the data. Decide wether you wish to render in Ham mode or register
  119. mode, and read the documentation on the hame.library to find out how to
  120. open a HamePort. Your RGB data will be rendered to fill the entire
  121. HamePort, so define your HamePort and screen accordingly.
  122.  
  123. Both of the renderers avoid using color 0 for any reason, thereby
  124. avoiding the possibility that blank lines will occur in the image and
  125. inadvertently turn off the HAME. In addition, both color 0 and color 1
  126. are set to black. Color 1 is used as a reference black within the
  127. image, and color 0 is used only where the Amiga sends all-zero data
  128. (such as at the edges of the image, in the overscan regions).
  129.  
  130. After you have obtained a valid HamePort pointer, you can go ahead and
  131. render your data. The following section describes each of the two
  132. rendering options:
  133.  
  134.  
  135.     void HAME_RenderHam(struct HamePort *h,
  136.                        struct rgb_image *rgb,
  137.                                     long left,
  138.                                     long top,
  139.                                     long wide,
  140.                                     long high,
  141.                                     long ebit);
  142.  
  143.     This rendering function uses the HAME mode to produce the most
  144.     accurate color display possible. The HamePort and rgb_image
  145.     pointers were described above. The left and top arguments describe
  146.     the location of the upper left corner of the source region you wish
  147.     to render while the wide and high parameters specify the width and
  148.     height of the source region.
  149.  
  150.     The indicated source region of the RGB buffers will be rendered into
  151.     the specified HamePort, filling the entire HamePort as defined in your
  152.     HAME_Init call. (see the hame.library docs for details) You should make
  153.     sure that you opened the HamePort in ham mode, or else the results will
  154.     fall far short of your expectations, IE look terrible.
  155.  
  156.     The "ebit" parameter is used to tell the library whether you want
  157.     the render to be done to eighteen bits precision, or if you want
  158.     the special 24 bit render techniques used. If you use 18 bit
  159.     techniques, then the image will be slightly less prone to fringing
  160.     in some cases where color changes are large and rapid. If you use
  161.     the 24 bit technique, the image will be rendered to a full 24 bit
  162.     accuracy, using a combination of carefully chosen (and placed) 24
  163.     bit color registers, and the EDD dithering techniques developed by
  164.     Black Belt Systems. 24 bit renders take slightly longer (10% or
  165.     so), and for the most part this is what the user is likely to want.
  166.     Set 'ebit" to 1 or 0 to tell the library what you want it to do.
  167.  
  168.  
  169.     void HAME_RenderReg(struct HamePort *h,
  170.                        struct rgb_image *rgb,
  171.                                     long left,
  172.                                     long top,
  173.                                     long wide,
  174.                                     long high,
  175.                                     long edd,
  176.                                     long last_reg);
  177.  
  178.     This rendering function uses register mode to produce its display.
  179.     The HamePort and rgb_image pointers are as described above. The left 
  180.     and top arguments describe the location of the upper left corner of 
  181.     the source region you wish to render while the wide and high parameters
  182.     specify the width and height of the source region.
  183.  
  184.     The indicated source region of the RGB buffers will be rendered into
  185.     the specified HamePort, filling the entire HamePort as defined in your
  186.     HAME_Init call. (see the hame.library docs for details) Make sure that
  187.     the HamePort was opened in register mode, or the render will look
  188.     terrible.
  189.  
  190.     The edd parameter allows you to specify special dithering
  191.     techniques that will extend the 256 available colors far beyond the
  192.     actual 256 color segment of the color space that they occupy. In
  193.     most cases, this is what you want. In some images, EDD may induce
  194.     more "graininess" than you want; more often, the image will be
  195.     actually smoother to the eye as a result.
  196.  
  197.     The last_reg parameter allows you to limit the number of registers
  198.     used by the renderer. This is a convenience feature that allows
  199.     you to keep some of the registers for your own use, without your
  200.     color choices adversely affecting the picture quality.
  201.  
  202.  
  203. int  HAME_SaveIFF(struct HamePort *h,
  204.                              char *name);
  205.  
  206.  
  207.      This is a simple IFF save function provided as a convenience.
  208.  (We're humanitarians - well, maybe we're not, but it sounds nice :^)
  209.  
  210.      Pass it your HamePort pointer and a FULL filename, and it will
  211.      save the screen as a standard 16 color IFF file that can be viewed
  212.      with any standard IFF viewer.
  213.  
  214.