home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 177.lha / FasText_v3.0 / FastText.doc < prev    next >
Encoding:
Text File  |  1988-04-28  |  5.6 KB  |  146 lines
  1. FastText revision 3.0 Copyright 1988 by Darren M. Greenwald
  2.  
  3. FastText is a copyrighted program.  It may be distributed freely, but it
  4. may NOT be sold/included in any way in any commercial, or shareware
  5. ventures without permission from the author.  It may be distributed in
  6. other public domain works so long as a notice of credit appears in the
  7. documentation.
  8.  
  9. FastText may be distributed as part of a public domain collection, and
  10. posted on telecommunication services so long as no additional charge is
  11. made above, and beyond the normal, and reasonable fees charged for
  12. the media, or use of system time.
  13.  
  14. If you would like permission to use this program in a commercial, or
  15. shareware venture, I can be contacted via the following methods:
  16.  
  17. On GEnie:               Send E-MAIL to DMG
  18. On Cute (714) 532-5698: Post a message in any forum to Darren Greenwald
  19. At Home:                (714) 545-6458
  20.  
  21. Including FastText in your programs -
  22.  
  23. FastText is written in assembly using the Manx Assembler.  Any changes
  24. needed to assemble this file with other assemblers is left up to you. 
  25. You need then only link the resulting object file with your code, and
  26. replace all calls too Text() with FastText().  In addition you must call the
  27. InitFastText() routine before calling FastText(), and finally call
  28. FreeFastText() as part of your cleanup/exit routine(s).  See the included
  29. FastText demo (Ftest.c) for an example of how easy this is to use.
  30.  
  31. In "C" format, the calls are defined like so:
  32.  
  33. InitFastText
  34. ------------
  35.  
  36. success=InitFastText(Font)
  37.  
  38. Inputs: Font - pointer to a TextFont structure
  39.  
  40. Return: TRUE, or FALSE
  41.  
  42. Description:
  43.  
  44. This routine does a number of things for you.  It checks to make sure that
  45. the font is a non-proportional font; it also checks to make sure the font
  46. is no less then 4 bits wide, but no more then 16 bits.  In any other case
  47. this routine returns FALSE.  Should this routine fail, you need not concern
  48. yourself too much.  In this case all calls to FastText() are automatically
  49. routed to call Text() instead.
  50.  
  51. Two CHIP RAM buffers are allocated based on the fonts height.  Fonts can be
  52. any height, but keep in mind that taller fonts use more memory.  One chip
  53. ram buffer is allocated for use as a buffer to draw the text imagery in, and
  54. the other is used to store the unpacked font data.
  55.  
  56. The font image data buffer requires 512 bytes * the font height.
  57.  
  58. The drawing buffer requires 128 bytes * the font height.
  59.  
  60. If this seems like a lot of memory, this is the trade off you make for the
  61. faster text rendering.  If the memory cannot be allocated, this routine
  62. will return FALSE, and all calls to FastText() are routed to call Text()
  63. instead.
  64.  
  65. Finally this routine upacks the font data, sets up the masks, blitter shift
  66. values, and some pointers to the image buffer.  Precalculating this
  67. stuff means that these calculations do not have to be done each time a line
  68. of text is rendered.
  69.  
  70. A special faster blitter routine is used for 8 bit wide fonts because 1.)
  71. Due to the way the blitter handles shifting it is possible to draw 8 bit
  72. wide fonts faster, and 2.) This works out well since 8 bit wide fonts are
  73. commonly used as the system font.
  74.  
  75. This routine should be called as part of your programs initialization
  76. procedures - it is your option to check for a return value since even if
  77. this fails, all calls to FastText() will automatically call Text() instead.
  78. This routine executes lickety-split; you won't have to wait "a moment" for
  79. the unpacking, and set-up to complete.
  80.  
  81. FastText
  82. --------
  83.  
  84. FastText(p,string,length)
  85.  
  86. Inputs: rp       - pointer to a rastport structure
  87.         string   - pointer to a string
  88.         length   - length of string to draw
  89.  
  90. Return: None
  91.  
  92. Description:
  93.  
  94. This call is very similar to Text().  It uses the exact same parameters
  95. as Text(), and behaves in a very similar manner.  You can set drawing
  96. colors (via SetAPen(), SetBPen()), drawing modes, etc.  The text position
  97. is set via the Move() function just like Text().
  98.  
  99. The X drawing position in the rastport is automatically incremented by the
  100. length (in pixels) of the string of text.
  101.  
  102. There are also some significant differences (speed of rendering included)!
  103.  
  104. Unlike Text() which draws a special image for non-defined characters in a
  105. font, FastText() draws undefined characters as blank spaces.  This could be
  106. changed if it causes anyone any problems.  I prefer it this way, but
  107. perhaps you may not?
  108.  
  109. FastText() does not currently support any font styles (e.g., bold,
  110. underline, italics).  This may be changed in the future.
  111.  
  112. The REVPATH flag is ignored.
  113.  
  114. FastText() treats NULL's as End of Line characters regardless of the length
  115. of string parameter.  This behavior can be changed if it causes anyone any
  116. problems.  I like it this way, but you may not.  Yes, this was intentional
  117. since it means I can call FastText(), and set the count to some large
  118. number rather then having to calculate the length of each string.  Text()
  119. on the other hand is terminated only by the length parameter, and will
  120. print NULL's as a non-printable character (usually a BOXY looking image).
  121.  
  122.  
  123. FreeFastText
  124. ------------
  125.  
  126. FreeFastText()
  127.  
  128. Inputs: None
  129.  
  130. Return: None
  131.  
  132. Description:
  133.  
  134. Frees memory allocated by InitFastText().  This routine can be called
  135. safely even if InitFastText() failed - in other words, it won't try to free
  136. memory which was never allocated.
  137.  
  138. ----------------------------------------------------------------------
  139.  
  140. Other notes:
  141.  
  142. It is very likely that this code is less then perfect.  Let the bug reports
  143. roll in!  Let me know, and I'll try to fix it ASAP.  Also hopefully I can
  144. further optimize the speed of the rendering routines.  In the future this
  145. whole thing may change anyway so that multiple fonts can be opened at the
  146. same time.