home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 505b.lha / Ham_e_library / hamelib.doc.pp / hamelib.doc
Encoding:
Text File  |  1991-05-05  |  22.3 KB  |  821 lines
  1. hame.library - documentation release 2.0
  2. ========================================
  3.  
  4. This library is released into the public domain. It may be
  5. redistributed without charge using any combination of electronic or
  6. magnetic media the user desires. The further it goes, the better off we
  7. all are.
  8.  
  9. hame.library software project credits:
  10. ======================================
  11.  
  12. Programming
  13. -----------
  14. Pete Patterson
  15.  
  16. Documentation
  17. -------------
  18. Pete Patterson, Ben Williams
  19.  
  20. Funding
  21. -------
  22. Black Belt Systems - Support for the HAM-E project.
  23.  
  24.  (NOTE: The Amiga community has a lot to thank Black Belt Systems for.
  25.   Here is my personal thanks to them for supporting quality Amiga
  26.   software development, and for ingenious inventions like the HAME.
  27.  
  28.                                                Pete Patterson        )
  29.  
  30. Introduction:
  31. =============
  32. This library works like most other amiga libraries such as the graphics
  33. library or intuition etc. To use this library in C code, you must
  34. declare a variable somewhere in your program as follows:
  35.  
  36.   struct Library *HameBase;
  37.  
  38. This variable is used to hold the base address of the hame library once
  39. it is loaded. Before using any of the functions within the library, you
  40. must open the library with something like the following 'C' code:
  41.  
  42.   HameBase = OpenLibrary("hame.library", 1L );
  43.   if ( HameBase == NULL )
  44.     {
  45.      /* clean up and exit... no hame.library available */
  46.     }
  47.  
  48. Of course, for this to work, the hame.library must be copied into your
  49. current libs: directory.
  50.  
  51. Once you have opened the library succesfully, you must set up a
  52. HamePort variable for each of the screens you want to put into HAME
  53. mode. This is done as follows...
  54.  
  55.    HamePort = 
  56.      HAME_Init( screen,twid,thi,vectors,mode,topline,cookies,scanlines);
  57.  
  58. ...where HamePort is declared as a "struct HamePort*" variable, and
  59. screen is a valid Intuition Screen pointer. This function allocates
  60. memory for the HamePort structure, initializes it and returns it to you
  61. for use in any further library calls. Be forewarned that most of the
  62. functions in this library cache the bitplane pointers from the screen
  63. and write directly into bitplane memory. This makes for very fast
  64. operation, but you MUST keep it in mind when manipulating the screen
  65. yourself.
  66.  
  67. The 'twid' and 'thi' parameters determine the size of the blitter data
  68. buffer allocated for this HamePort. This should be as large as the
  69. largest area you plan to fill with any of the drawing routines that
  70. fill a region.  The vectors parameter determines the number of entries
  71. to allocate for area fill operations. Set this to at least as many
  72. scanlines as the largest ellipse you will draw.
  73.  
  74. The mode parameter determines what type of cookie will be written, and
  75. the topline and cookies parameters determine where the cookie is
  76. written, and how many scanlines of cookie data to write. A mode
  77. parameter of zero produces a register mode cookie, while a mode
  78. parameter of one will write a ham cookie. Note that if the screen is
  79. interlaced, then twice as many cookie lines will be written.
  80.  
  81. The scanlines parameter determines the height of the HamePort. All
  82. rendering is automatically clipped to the limits of the HamePort.
  83.  
  84. When you want to close down hame operations, simply call HAME_Dispose()
  85. once for each of your HamePorts. Once all HamePorts are closed, call
  86. CloseLibrary(HameBase) and you are done.
  87.  
  88. The library functions available for this release deal with three unique
  89. structures. These structures are the HameFont structure, the Clip
  90. structure and the HamePort structure. At present, we do not encourage
  91. or support any use of the internal variables within these structures.
  92. They are simply "bags of data" with which the library keeps track of
  93. multiple users. As a programmer, you will usually just pass pointers to
  94. these objects amongst the various library routines. The only exceptions
  95. to this rule are the use of the HamePort->r, HamePort->g and HamePort-
  96. >b members which hold the red, green and blue values after a call to
  97. HAME_GetRGB8, and the HameFont->NColors and HameFont->BaseLine variables
  98. which gives the number of colors and the baseline of a successfully 
  99. opened font.
  100.  
  101. Having said this, it may be useful for you to know that the HamePort
  102. structure is used to manipulate or draw on an actual screen; A HameFont
  103. structure is also used to track access to a font or colorfont, and a
  104. Clip structure is used to manipulate rectangular regions of graphics
  105. data.
  106.  
  107. Here is a description of each of the library functions.
  108.  
  109. HAME_Init( ScreenPtr,twid,thi,vectors,mode,topline,cookies,scanlines )
  110. -----------------------------------------------------------
  111. Opens a HamePort on the given screen. A blitter fill buffer is allocated
  112. according to the size arguments 'twid' and 'thi'. 'vectors' should be
  113. equal to the maximum number of scanlines you will attempt to draw an ellipse
  114. with. 'mode' is either 0 or 1 to enable register mode or hame mode
  115. respectively. 'topline' is the first screen line to write the cookie on,
  116. and 'cookies' is the number of palette lines to write. Note that if the
  117. screen is interlaced, twice as many scanlines will be used, so take
  118. that into account when calculating the height of the hameport.
  119.  
  120. The final parameter, scanlines, determines the height of the drawing area 
  121. of this HamePort. All rendering operations will be clipped to the extents
  122. of the HamePort.
  123.  
  124. This function returns a pointer to a HamePort structure.
  125.  
  126.   SEE ALSO:
  127.      HAME_Init
  128.  
  129.   RETURNS:
  130.      struct HamePort *
  131.  
  132.  
  133. HAME_Dispose(HamePort)
  134. ----------------------
  135. This function frees the memory associated with the HamePort structure.
  136. Note that you should not free this memory yourself; This function must
  137. only be called with a valid pointer that was obtained with HameInit.
  138.  
  139.   NOTE: BASIC users getting their HamePort from HAME_OpenScreen MUST NOT
  140.   use this function to free the HamePort. They should use HAME_CloseScreen
  141.   instead.
  142.  
  143.   SEE ALSO:
  144.      HAME_Init
  145.  
  146.   RETURNS:
  147.      VOID
  148.  
  149.  
  150. HAME_SetAPen(HamePort,color)
  151. ----------------------------
  152. This function sets the foreground color of the given HamePort to color
  153. 'color'. The foreground pen is used for all drawing operations.
  154.  
  155.   SEE ALSO:
  156.      HAME_SetBPen
  157.  
  158.   RETURNS:
  159.      VOID
  160.  
  161.  
  162. HAME_SetBPen(HamePort,color)
  163. ----------------------------
  164. This function sets the background color of the given HamePort to color
  165. 'color'. The background pen is currently only used for backfilling screen
  166. areas after HAME_Scroll is called.
  167.  
  168.   SEE ALSO:
  169.      HAME_SetAPen
  170.  
  171.   RETURNS:
  172.      VOID
  173.  
  174. HAME_ReadPixel(HamePort, x, y)
  175. ------------------------------
  176. This function returns the 8 bit value of the pixel at position x,y.
  177.  
  178.   SEE ALSO:
  179.      HAME_WritePixel
  180.  
  181.   RETURNS:
  182.      int
  183.  
  184. HAME_WritePixel(HamePort, x, y)
  185. ----------------------------------
  186. This function sets the pixel at position x,y to the current foreground
  187. color of the HamePort. Unless you are *absolutely* sure that intuition
  188. will not try to draw on your screen, you must call HAME_LockLayer(HamePort)
  189. before writing the pixel, and HAME_UnlockLayer(HamePort) after you have
  190. finished. Failure to do this will result in loss of data and trashing of
  191. intuition rendered objects.
  192.  
  193. It is permitted (encouraged in fact) for you to lock the layer and then
  194. write a whole bunch of pixels before unlocking, but you *MUST* not
  195. use any of the other hame.library routines except for HAME_SetAPen. You 
  196. should not lock the layers for extreme periods, however, or the user will 
  197. never get a chance to pull down menus or whatever.
  198.  
  199. For example, if you are writing a rectangular group of pixels using dual
  200. nested loops, implement the locking like so:
  201.  
  202.   for ( y = line1; y <= line2; y++ )
  203.     {
  204.       HAME_LockLayer(HamePort);
  205.       for ( x = column1; x <= column2; x++ )
  206.         {
  207.           HAME_WritePixel(HamePort, x, y );
  208.         }
  209.       HAME_UnlockLayer(HamePort);
  210.     }
  211.  
  212. The reason we chose to make you do this is that locking the layers takes
  213. a relatively long time, and individual pixels are typically written in
  214. large groups. The overhead of locking the layers multiplied by the large
  215. number of pixels you will typically write would make your application
  216. run significantly slower if this were done for each pixel.
  217.  
  218.  
  219.   SEE ALSO:
  220.      HAME_ReadPixel
  221.      HAME_LockLayer
  222.      HAME_UnlockLayer
  223.  
  224.   RETURNS:
  225.      VOID
  226.  
  227.  
  228. HAME_GetRGBPixel(HamePort,x,y)
  229. ------------------------------
  230. This function sets the r, g, and b elements of the HamePort structure to
  231. the red, green and blue values of the pixel at location x,y. This will work
  232. on both register mode and ham mode screens.
  233.  
  234.   SEE ALSO:
  235.      HAME_GetRGB8
  236.      HAME_SetRGB8
  237.  
  238.   RETURNS:
  239.      VOID
  240.  
  241. HAME_GetRGB8(HamePort,reg)
  242. --------------------------
  243. This function sets the r, g, and b elements of the HamePort structure to
  244. the red, green and blue values of color register reg.
  245.  
  246. This function does not return a value directly.
  247.  
  248.   SEE ALSO:
  249.      HAME_SetRGB8
  250.      HAME_GetRGBPixel
  251.  
  252.   RETURNS:
  253.      VOID
  254.  
  255. HAME_SetRGB8(HamePort,reg,r,g,b)
  256. --------------------------------
  257. This function sets the r, g, and b values of color register number reg.
  258.  
  259.   SEE ALSO:
  260.      HAME_GetRGB8
  261.      HAME_GetRGBPixel
  262.  
  263.   RETURNS:
  264.      VOID
  265.  
  266. HAME_Ellipse(HamePort,x,y,width,height,fill)
  267. --------------------------------------------
  268. This function draws an ellipse centered at x,y with an x radius of width
  269. and a y radius of height. The color of the ellipse will be the current
  270. foreground color of the HamePort, and if 'fill' is equal to 1, the 
  271. ellipse will be filled with the current foreground color.
  272.  
  273.   SEE ALSO:
  274.      HAME_Box
  275.      HAME_Line
  276.  
  277.   RETURNS:
  278.      VOID
  279.  
  280. HAME_Line(HamePort,x1,y1,x2,y2)
  281. -------------------------------
  282. This function draws a line from x1,y1 to x2,y2. The color of the line
  283. will be the current foreground color.
  284.  
  285.   SEE ALSO:
  286.      HAME_Box
  287.      HAME_Ellipse
  288.  
  289.   RETURNS:
  290.      VOID
  291.  
  292. HAME_Box(HamePort,x1,y1,x2,y2,filled)
  293. -------------------------------------
  294. This function draws a box from x1,y1 to x2,y2. The color of the box
  295. will be color 'colr', and if filled equals 1, then the box will be filled
  296. with the current foreground color.
  297.  
  298.   SEE ALSO:
  299.      HAME_Ellipse
  300.      HAME_Line
  301.  
  302.   RETURNS:
  303.      VOID
  304.  
  305. HAME_OpenScreen(lace,ham,Width,Height)
  306. --------------------------------------
  307. This function is intended to aid BASIC users. It returns a HamePort
  308. pointer after opening a screen with a borderless backdrop window on it.
  309. Both the screen and the window will be the given width and height.
  310. If ham equals 1 the screen will have a ham cookie on it, otherwise a 
  311. register cookie will be written. HamePort->Screen will have the screen 
  312. pointer in it, and HamePort->Window will have the window pointer.
  313.  
  314.   NOTE: This is the only time that you should use these structure
  315.         members.
  316.  
  317.   SEE ALSO:
  318.      HAME_CloseScreen
  319.  
  320.   RETURNS:
  321.      struct HamePort *
  322.  
  323. HAME_CloseScreen(HamePort)
  324. --------------------------
  325. This function closes the screen and window obtained by HAME_OpenScreen,
  326. and Disposes of the HamePort structure as well.
  327.  
  328.   SEE ALSO:
  329.      HAME_OpenScreen
  330.  
  331.   RETURNS:
  332.      VOID
  333.  
  334. HAME_CycleLeft(HamePort, start, end)
  335. ------------------------------------
  336. This function cycles the hame color palette left (from higher registers
  337. down into the lower ones). All colors between start and end will be
  338. affected, and the last color will be wrapped back into the first color.
  339.  
  340.   SEE ALSO:
  341.      HAME_CycleRight
  342.  
  343.   RETURNS:
  344.      VOID
  345.  
  346. HAME_CycleRight(HamePort, start, end)
  347. -------------------------------------
  348. This function cycles the hame color palette right (from lower registers
  349. up into the higher ones). All colors between start and end will be
  350. affected, and the last color will be wrapped back into the first color.
  351.  
  352.   SEE ALSO:
  353.      HAME_CycleLeft
  354.  
  355.   RETURNS:
  356.      VOID
  357.  
  358. HAME_Move( HamePort, x, y )
  359. ---------------------------
  360. This function places the drawing cursor at position x,y in preperation
  361. for future HAME_Draw instructions.
  362.  
  363.   SEE ALSO:
  364.      HAME_Draw
  365.  
  366.   RETURNS:
  367.      VOID
  368.  
  369. HAME_Draw( HamePort, x, y )
  370. ---------------------------
  371. This function draws a line in the current foreground color from the
  372. position of the current drawing cursor to location x,y. It also updates
  373. the location of the drawing cursor for subsequent HAME_Draw commands.
  374.  
  375.   SEE ALSO:
  376.      HAME_Move
  377.  
  378.   RETURNS:
  379.      VOID
  380.  
  381.  
  382. HAME_8BitRender( HamePort, BuffAddr, x, y, wid, high )
  383. ------------------------------------------------------
  384. This function renders to a HamePort screen from a buffer of 8 bit
  385. values. The 8 bit values represent register values for individual
  386. pixels, and will generally be kept in FAST ram. The 'wid' and 'high'
  387. parameters indicate both the size of the 8 bit pixel data area, and the
  388. amount of data to render. The HamePort and the 'x' and 'y' parameters
  389. indicate where to place the rendered data. Note that the palette is not
  390. affected by this call.
  391.  
  392.   SEE ALSO:
  393.  
  394.   RETURNS:
  395.      VOID
  396.  
  397. HAME_Scroll( HamePort, dx, dy, x1, y1, x2, y2)
  398. ----------------------------------------------
  399. This routine scrolls the region of the screen delimited by (x1,y1)-
  400. (x2,y2) by the amounts indicated by dx and dy. The newly vacated areas
  401. of the screen are filled with the HamePorts current background color.
  402.  
  403.   SEE ALSO:
  404.  
  405.   RETURNS:
  406.      VOID
  407.  
  408. HAME_OpenFont( fontname, size )
  409. -------------------------------
  410. Opens the indicated font if it exists, and returns a HameFont pointer. 
  411. The font must exist in the correct size, or the call will fail. Both
  412. normal and colorfonts are supported, but for correct colorfont
  413. operation, the ColorText program must be currently running.
  414.  
  415. After opening the font, you can examine font->NColors to find out
  416. how many colors are in the font (minimum of two), and font->BaseLine
  417. to determine the baseline of the font you have opened.
  418.  
  419.   SEE ALSO:
  420.      HAME_GetFontPallete
  421.      HAME_SetFontPen
  422.      HAME_Text
  423.      HAME_MakeFTables
  424.      HAME_QText
  425.      HAME_CloseFont
  426.  
  427.   RETURNS:
  428.      struct HameFont *
  429.  
  430.  
  431. HAME_GetFontPallete( HamePort, Font )
  432. -------------------------------------
  433. This call will stuff the HamePorts palette with the correct color
  434. values if the Font is a colorfont. The colors will be stuffed into the
  435. HamePorts pallete starting at the current Foreground color as defined
  436. By HAME_SetAPen. The number of colors in the pallete is returned.
  437.  
  438.   SEE ALSO:
  439.      HAME_OpenFont
  440.      HAME_SetFontPen
  441.      HAME_Text
  442.      HAME_MakeFTables
  443.      HAME_QText
  444.      HAME_CloseFont
  445.  
  446.   RETURNS:
  447.      int
  448.  
  449. HAME_SetFontPen( Font, color )
  450. ------------------------------
  451. Sets the font base color for the given font. All HAME_Text calls use
  452. the current Font pen to determine the color for single color fonts, and
  453. to replace the variable color in colorfonts. This font pen has no
  454. effect on text rendered by HAME_QText.
  455.  
  456.   SEE ALSO:
  457.      HAME_OpenFont
  458.      HAME_GetFontPallete
  459.      HAME_Text
  460.      HAME_MakeFTables
  461.      HAME_QText
  462.      HAME_CloseFont
  463.  
  464.   RETURNS:
  465.      VOID
  466.  
  467.  
  468. HAME_Text(HamePort, Font, string, x, y )
  469. ----------------------------------------
  470. This renders the given string into the HamePort at position x,y using
  471. the given font. It returns the width in Hame pixels of the rendered
  472. text.
  473.  
  474.   SEE ALSO:
  475.      HAME_OpenFont
  476.      HAME_GetFontPallete
  477.      HAME_SetFontPen
  478.      HAME_MakeFTables
  479.      HAME_QText
  480.      HAME_CloseFont
  481.  
  482.   RETURNS:
  483.      int
  484.  
  485.  
  486. HAME_MakeFTables( Font, basecolor )
  487. -----------------------------------
  488. You must call this routine if you intend to use the HAME_QText routine.
  489. This routine precalculates certain tables which allow the text to be
  490. rendered much faster than HAME_Text, but with certain minor but
  491. important restrictions. You supply a HameFont pointer and the basecolor
  492. to be used by the font.
  493.  
  494. Any text subsequently rendered with QText will map into the palette
  495. starting at the given basecolor.
  496.  
  497.   As for the restrictions, they are currently:
  498.  
  499.     basecolor must be an exact multiple of sixteen
  500.     the number of colors in the font must be 16 or less
  501.  
  502.   This routine WILL work with non colorfonts
  503.  
  504.   SEE ALSO:
  505.      HAME_OpenFont
  506.      HAME_GetFontPallete
  507.      HAME_SetFontPen
  508.      HAME_Text
  509.      HAME_QText
  510.      HAME_CloseFont
  511.  
  512.   RETURNS:
  513.      VOID
  514.  
  515. HAME_QText(HamePort, Font, string, x, y )
  516. -----------------------------------------
  517. This is a quick text rendering routine that uses the tables
  518. precalculated by HAME_MakeFTables. It takes the same arguments as
  519. HAME_Text, but suffers (benefits?) from the restrictions outlined under
  520. HAME_MakeFTables.
  521.  
  522.   Returns the width, in hame pixels, of the rendered text.
  523.  
  524.   SEE ALSO:
  525.      HAME_OpenFont
  526.      HAME_GetFontPallete
  527.      HAME_SetFontPen
  528.      HAME_Text
  529.      HAME_MakeFTables
  530.      HAME_CloseFont
  531.  
  532.   RETURNS:
  533.      int
  534.  
  535. HAME_CloseFont(Font)
  536. --------------------
  537.   Closes a HameFont.
  538.  
  539.   SEE ALSO:
  540.      HAME_OpenFont
  541.      HAME_GetFontPallete
  542.      HAME_SetFontPen
  543.      HAME_Text
  544.      HAME_QText
  545.      HAME_MakeFTables
  546.  
  547.   RETURNS:
  548.      VOID
  549.  
  550. HAME_AllocClip( Width, Height, MaskFlag )
  551. -----------------------------------------
  552. Allocates a clip structure and bitplane memory for a clip of the given
  553. size. If MaskFlag is 1, then an additional bitplane will be allocated
  554. for masked clip operations.
  555.  
  556.   SEE ALSO:
  557.     HAME_DisposeClip
  558.     HAME_GetClip
  559.     HAME_PutClip
  560.     HAME_ReadClipPixel
  561.     HAME_WriteClipPixel
  562.     HAME_ReadMaskPixel
  563.     HAME_WriteMaskPixel
  564.     HAME_AllocClipMask
  565.     HAME_DisposeClipMask
  566.     HAME_MakeClipMask
  567.  
  568.   RETURNS:
  569.      struct Clip *
  570.  
  571. HAME_DisposeClip( clip )
  572. ------------------------
  573. This frees all memory associated with the given clip, including
  574. bitplane memory, mask memory and the clip structure itself.
  575.  
  576.   SEE ALSO:
  577.     HAME_AllocClip
  578.     HAME_GetClip
  579.     HAME_PutClip
  580.     HAME_ReadClipPixel
  581.     HAME_WriteClipPixel
  582.     HAME_ReadMaskPixel
  583.     HAME_WriteMaskPixel
  584.     HAME_AllocClipMask
  585.     HAME_DisposeClipMask
  586.     HAME_MakeClipMask
  587.  
  588.   RETURNS:
  589.      VOID
  590.  
  591.  
  592. HAME_GetClip( HamePort, x, y, width, height )
  593. ---------------------------------------------
  594. Allocates a clip of the given width and height and fills it with data
  595. from position x,y of the given HamePort. No mask is created for the
  596. clip.
  597.  
  598.   SEE ALSO:
  599.     HAME_AllocClip
  600.     HAME_DisposeClip
  601.     HAME_PutClip
  602.     HAME_ReadClipPixel
  603.     HAME_WriteClipPixel
  604.     HAME_ReadMaskPixel
  605.     HAME_WriteMaskPixel
  606.     HAME_AllocClipMask
  607.     HAME_DisposeClipMask
  608.     HAME_MakeClipMask
  609.  
  610.   RETURNS:
  611.      struct Clip *
  612.  
  613.  
  614. HAME_PutClip( HamePort, clip, x, y )
  615. ------------------------------------
  616. Renders the clip data into the given HamePort at position x,y.
  617.  
  618.   SEE ALSO:
  619.     HAME_AllocClip
  620.     HAME_DisposeClip
  621.     HAME_GetClip
  622.     HAME_ReadClipPixel
  623.     HAME_WriteClipPixel
  624.     HAME_ReadMaskPixel
  625.     HAME_WriteMaskPixel
  626.     HAME_AllocClipMask
  627.     HAME_DisposeClipMask
  628.     HAME_MakeClipMask
  629.  
  630.   RETURNS:
  631.      VOID
  632.  
  633. HAME_ReadClipPixel( clip, x, y )
  634. --------------------------------
  635. Reads and returns the 8 bit pixel value at position x,y of the given clip.
  636.  
  637.   SEE ALSO:
  638.     HAME_AllocClip
  639.     HAME_DisposeClip
  640.     HAME_GetClip
  641.     HAME_PutClip
  642.     HAME_WriteClipPixel
  643.     HAME_ReadMaskPixel
  644.     HAME_WriteMaskPixel
  645.     HAME_AllocClipMask
  646.     HAME_DisposeClipMask
  647.     HAME_MakeClipMask
  648.  
  649.   RETURNS:
  650.      int
  651.  
  652.  
  653. HAME_WriteClipPixel( clip, x, y, reg )
  654. --------------------------------------
  655. Writes the 8 bit pixel value 'reg' into position x,y of the given clip.
  656.  
  657.   SEE ALSO:
  658.     HAME_AllocClip
  659.     HAME_DisposeClip
  660.     HAME_GetClip
  661.     HAME_PutClip
  662.     HAME_ReadClipPixel
  663.     HAME_ReadMaskPixel
  664.     HAME_WriteMaskPixel
  665.     HAME_AllocClipMask
  666.     HAME_DisposeClipMask
  667.     HAME_MakeClipMask
  668.  
  669.   RETURNS:
  670.      VOID
  671.  
  672.  
  673. HAME_ReadMaskPixel( clip, x, y )
  674. --------------------------------
  675. Reads and returns the 1 bit pixel value at position x,y of the given
  676. clips mask.
  677.  
  678.   SEE ALSO:
  679.     HAME_AllocClip
  680.     HAME_DisposeClip
  681.     HAME_GetClip
  682.     HAME_PutClip
  683.     HAME_ReadClipPixel
  684.     HAME_WriteClipPixel
  685.     HAME_WriteMaskPixel
  686.     HAME_AllocClipMask
  687.     HAME_DisposeClipMask
  688.     HAME_MakeClipMask
  689.  
  690.   RETURNS:
  691.      int
  692.  
  693.  
  694. HAME_WriteMaskPixel( clip, x, y, v )
  695. ------------------------------------
  696. Writes the 1 bit pixel value 'v' into position x,y of the given clip.
  697.  
  698.   SEE ALSO:
  699.     HAME_AllocClip
  700.     HAME_DisposeClip
  701.     HAME_GetClip
  702.     HAME_PutClip
  703.     HAME_ReadClipPixel
  704.     HAME_WriteClipPixel
  705.     HAME_ReadMaskPixel
  706.     HAME_AllocClipMask
  707.     HAME_DisposeClipMask
  708.     HAME_MakeClipMask
  709.  
  710.   RETURNS:
  711.      VOID
  712.  
  713.  
  714. HAME_AllocClipMask( clip )
  715. --------------------------
  716. Allocates a mask for the given clip. The mask will be the same width
  717. and height as the clip. This mask is already linked to the clip, but the
  718. Mask pointer itself is returned to let you know if the Allocation failed.
  719. If the pointer is NULL, you didn't get the mask.
  720.  
  721.   SEE ALSO:
  722.     HAME_AllocClip
  723.     HAME_DisposeClip
  724.     HAME_GetClip
  725.     HAME_PutClip
  726.     HAME_ReadClipPixel
  727.     HAME_WriteClipPixel
  728.     HAME_ReadMaskPixel
  729.     HAME_WriteMaskPixel
  730.     HAME_DisposeClipMask
  731.     HAME_MakeClipMask
  732.  
  733.   RETURNS:
  734.      UWORD *
  735.  
  736.  
  737. HAME_DisposeClipMask( clip )
  738. ----------------------------
  739. Frees the memory used by a clips mask.
  740.  
  741.   SEE ALSO:
  742.     HAME_AllocClip
  743.     HAME_DisposeClip
  744.     HAME_GetClip
  745.     HAME_PutClip
  746.     HAME_ReadClipPixel
  747.     HAME_WriteClipPixel
  748.     HAME_ReadMaskPixel
  749.     HAME_WriteMaskPixel
  750.     HAME_AllocClipMask
  751.     HAME_MakeClipMask
  752.  
  753.   RETURNS:
  754.      VOID
  755.  
  756. HAME_MakeClipMask( clip, transcolor )
  757. -------------------------------------
  758. Examines each pixel of the given clip, and sets the masks pixels
  759. accordingly. The 'transcolor' indicates what register value should be
  760. considered transparent. This mask will be used to restrict changes to
  761. the display to those areas of the screen where the mask is non-zero.
  762.  
  763.   SEE ALSO:
  764.     HAME_AllocClip
  765.     HAME_DisposeClip
  766.     HAME_GetClip
  767.     HAME_PutClip
  768.     HAME_ReadClipPixel
  769.     HAME_WriteClipPixel
  770.     HAME_ReadMaskPixel
  771.     HAME_WriteMaskPixel
  772.     HAME_AllocClipMask
  773.     HAME_DisposeClipMask
  774.  
  775.   RETURNS:
  776.      VOID
  777.  
  778.  
  779. HAME_WaitScanline( HamePort, scanline )
  780. ---------------------------------------
  781. POLLS the video beam pointer until it is past the scanline indicated.
  782.  
  783.   CAVEAT: THIS IS A BUSY WAIT LOOP
  784.  
  785.   SEE ALSO:
  786.  
  787.   RETURNS:
  788.      VOID
  789.  
  790. HAME_LockLayer( HamePort )
  791. --------------------------
  792. Locks all intuition layers from drawing into the screen this HamePort
  793. was opened on. In practical terms, this prevents the library routines
  794. (most of which write directly into bitplane memory) from trashing
  795. Intuition rendered items such as menus. When this call returns, you
  796. are free to render directly into the screens bitplanes without fear
  797. of the user pulling down a menu into which your data will be rendered.
  798. You *MUST* call this routine before you call HAME_WritePixel.
  799.  
  800.   SEE ALSO:
  801.      HAME_WritePixel
  802.      HAME_LockLayer.
  803.  
  804.   RETURNS:
  805.      VOID
  806.  
  807.  
  808. HAME_UnlockLayer( HamePort )
  809. ----------------------------
  810. Allows intuition (or other well behaved routines) to write into the
  811. screen that the HamePort was opened on. You *MUST* call this routine
  812. after you are finished using the HAME_WritePixel function.
  813.  
  814.   SEE ALSO:
  815.      HAME_WritePixel
  816.      HAME_LockLayer.
  817.  
  818.   RETURNS:
  819.      VOID
  820. /**/
  821.