hame.library - documentation release 2.0 ======================================== This library is released into the public domain. It may be redistributed without charge using any combination of electronic or magnetic media the user desires. The further it goes, the better off we all are. hame.library software project credits: ====================================== Programming ----------- Pete Patterson Documentation ------------- Pete Patterson, Ben Williams Funding ------- Black Belt Systems - Support for the HAM-E project. (NOTE: The Amiga community has a lot to thank Black Belt Systems for. Here is my personal thanks to them for supporting quality Amiga software development, and for ingenious inventions like the HAME. Pete Patterson ) Introduction: ============= This library works like most other amiga libraries such as the graphics library or intuition etc. To use this library in C code, you must declare a variable somewhere in your program as follows: struct Library *HameBase; This variable is used to hold the base address of the hame library once it is loaded. Before using any of the functions within the library, you must open the library with something like the following 'C' code: HameBase = OpenLibrary("hame.library", 1L ); if ( HameBase == NULL ) { /* clean up and exit... no hame.library available */ } Of course, for this to work, the hame.library must be copied into your current libs: directory. Once you have opened the library succesfully, you must set up a HamePort variable for each of the screens you want to put into HAME mode. This is done as follows... HamePort = HAME_Init( screen,twid,thi,vectors,mode,topline,cookies,scanlines); ...where HamePort is declared as a "struct HamePort*" variable, and screen is a valid Intuition Screen pointer. This function allocates memory for the HamePort structure, initializes it and returns it to you for use in any further library calls. Be forewarned that most of the functions in this library cache the bitplane pointers from the screen and write directly into bitplane memory. This makes for very fast operation, but you MUST keep it in mind when manipulating the screen yourself. The 'twid' and 'thi' parameters determine the size of the blitter data buffer allocated for this HamePort. This should be as large as the largest area you plan to fill with any of the drawing routines that fill a region. The vectors parameter determines the number of entries to allocate for area fill operations. Set this to at least as many scanlines as the largest ellipse you will draw. The mode parameter determines what type of cookie will be written, and the topline and cookies parameters determine where the cookie is written, and how many scanlines of cookie data to write. A mode parameter of zero produces a register mode cookie, while a mode parameter of one will write a ham cookie. Note that if the screen is interlaced, then twice as many cookie lines will be written. The scanlines parameter determines the height of the HamePort. All rendering is automatically clipped to the limits of the HamePort. When you want to close down hame operations, simply call HAME_Dispose() once for each of your HamePorts. Once all HamePorts are closed, call CloseLibrary(HameBase) and you are done. The library functions available for this release deal with three unique structures. These structures are the HameFont structure, the Clip structure and the HamePort structure. At present, we do not encourage or support any use of the internal variables within these structures. They are simply "bags of data" with which the library keeps track of multiple users. As a programmer, you will usually just pass pointers to these objects amongst the various library routines. The only exceptions to this rule are the use of the HamePort->r, HamePort->g and HamePort- >b members which hold the red, green and blue values after a call to HAME_GetRGB8, and the HameFont->NColors and HameFont->BaseLine variables which gives the number of colors and the baseline of a successfully opened font. Having said this, it may be useful for you to know that the HamePort structure is used to manipulate or draw on an actual screen; A HameFont structure is also used to track access to a font or colorfont, and a Clip structure is used to manipulate rectangular regions of graphics data. Here is a description of each of the library functions. HAME_Init( ScreenPtr,twid,thi,vectors,mode,topline,cookies,scanlines ) ----------------------------------------------------------- Opens a HamePort on the given screen. A blitter fill buffer is allocated according to the size arguments 'twid' and 'thi'. 'vectors' should be equal to the maximum number of scanlines you will attempt to draw an ellipse with. 'mode' is either 0 or 1 to enable register mode or hame mode respectively. 'topline' is the first screen line to write the cookie on, and 'cookies' is the number of palette lines to write. Note that if the screen is interlaced, twice as many scanlines will be used, so take that into account when calculating the height of the hameport. The final parameter, scanlines, determines the height of the drawing area of this HamePort. All rendering operations will be clipped to the extents of the HamePort. This function returns a pointer to a HamePort structure. SEE ALSO: HAME_Init RETURNS: struct HamePort * HAME_Dispose(HamePort) ---------------------- This function frees the memory associated with the HamePort structure. Note that you should not free this memory yourself; This function must only be called with a valid pointer that was obtained with HameInit. NOTE: BASIC users getting their HamePort from HAME_OpenScreen MUST NOT use this function to free the HamePort. They should use HAME_CloseScreen instead. SEE ALSO: HAME_Init RETURNS: VOID HAME_SetAPen(HamePort,color) ---------------------------- This function sets the foreground color of the given HamePort to color 'color'. The foreground pen is used for all drawing operations. SEE ALSO: HAME_SetBPen RETURNS: VOID HAME_SetBPen(HamePort,color) ---------------------------- This function sets the background color of the given HamePort to color 'color'. The background pen is currently only used for backfilling screen areas after HAME_Scroll is called. SEE ALSO: HAME_SetAPen RETURNS: VOID HAME_ReadPixel(HamePort, x, y) ------------------------------ This function returns the 8 bit value of the pixel at position x,y. SEE ALSO: HAME_WritePixel RETURNS: int HAME_WritePixel(HamePort, x, y) ---------------------------------- This function sets the pixel at position x,y to the current foreground color of the HamePort. Unless you are *absolutely* sure that intuition will not try to draw on your screen, you must call HAME_LockLayer(HamePort) before writing the pixel, and HAME_UnlockLayer(HamePort) after you have finished. Failure to do this will result in loss of data and trashing of intuition rendered objects. It is permitted (encouraged in fact) for you to lock the layer and then write a whole bunch of pixels before unlocking, but you *MUST* not use any of the other hame.library routines except for HAME_SetAPen. You should not lock the layers for extreme periods, however, or the user will never get a chance to pull down menus or whatever. For example, if you are writing a rectangular group of pixels using dual nested loops, implement the locking like so: for ( y = line1; y <= line2; y++ ) { HAME_LockLayer(HamePort); for ( x = column1; x <= column2; x++ ) { HAME_WritePixel(HamePort, x, y ); } HAME_UnlockLayer(HamePort); } The reason we chose to make you do this is that locking the layers takes a relatively long time, and individual pixels are typically written in large groups. The overhead of locking the layers multiplied by the large number of pixels you will typically write would make your application run significantly slower if this were done for each pixel. SEE ALSO: HAME_ReadPixel HAME_LockLayer HAME_UnlockLayer RETURNS: VOID HAME_GetRGBPixel(HamePort,x,y) ------------------------------ This function sets the r, g, and b elements of the HamePort structure to the red, green and blue values of the pixel at location x,y. This will work on both register mode and ham mode screens. SEE ALSO: HAME_GetRGB8 HAME_SetRGB8 RETURNS: VOID HAME_GetRGB8(HamePort,reg) -------------------------- This function sets the r, g, and b elements of the HamePort structure to the red, green and blue values of color register reg. This function does not return a value directly. SEE ALSO: HAME_SetRGB8 HAME_GetRGBPixel RETURNS: VOID HAME_SetRGB8(HamePort,reg,r,g,b) -------------------------------- This function sets the r, g, and b values of color register number reg. SEE ALSO: HAME_GetRGB8 HAME_GetRGBPixel RETURNS: VOID HAME_Ellipse(HamePort,x,y,width,height,fill) -------------------------------------------- This function draws an ellipse centered at x,y with an x radius of width and a y radius of height. The color of the ellipse will be the current foreground color of the HamePort, and if 'fill' is equal to 1, the ellipse will be filled with the current foreground color. SEE ALSO: HAME_Box HAME_Line RETURNS: VOID HAME_Line(HamePort,x1,y1,x2,y2) ------------------------------- This function draws a line from x1,y1 to x2,y2. The color of the line will be the current foreground color. SEE ALSO: HAME_Box HAME_Ellipse RETURNS: VOID HAME_Box(HamePort,x1,y1,x2,y2,filled) ------------------------------------- This function draws a box from x1,y1 to x2,y2. The color of the box will be color 'colr', and if filled equals 1, then the box will be filled with the current foreground color. SEE ALSO: HAME_Ellipse HAME_Line RETURNS: VOID HAME_OpenScreen(lace,ham,Width,Height) -------------------------------------- This function is intended to aid BASIC users. It returns a HamePort pointer after opening a screen with a borderless backdrop window on it. Both the screen and the window will be the given width and height. If ham equals 1 the screen will have a ham cookie on it, otherwise a register cookie will be written. HamePort->Screen will have the screen pointer in it, and HamePort->Window will have the window pointer. NOTE: This is the only time that you should use these structure members. SEE ALSO: HAME_CloseScreen RETURNS: struct HamePort * HAME_CloseScreen(HamePort) -------------------------- This function closes the screen and window obtained by HAME_OpenScreen, and Disposes of the HamePort structure as well. SEE ALSO: HAME_OpenScreen RETURNS: VOID HAME_CycleLeft(HamePort, start, end) ------------------------------------ This function cycles the hame color palette left (from higher registers down into the lower ones). All colors between start and end will be affected, and the last color will be wrapped back into the first color. SEE ALSO: HAME_CycleRight RETURNS: VOID HAME_CycleRight(HamePort, start, end) ------------------------------------- This function cycles the hame color palette right (from lower registers up into the higher ones). All colors between start and end will be affected, and the last color will be wrapped back into the first color. SEE ALSO: HAME_CycleLeft RETURNS: VOID HAME_Move( HamePort, x, y ) --------------------------- This function places the drawing cursor at position x,y in preperation for future HAME_Draw instructions. SEE ALSO: HAME_Draw RETURNS: VOID HAME_Draw( HamePort, x, y ) --------------------------- This function draws a line in the current foreground color from the position of the current drawing cursor to location x,y. It also updates the location of the drawing cursor for subsequent HAME_Draw commands. SEE ALSO: HAME_Move RETURNS: VOID HAME_8BitRender( HamePort, BuffAddr, x, y, wid, high ) ------------------------------------------------------ This function renders to a HamePort screen from a buffer of 8 bit values. The 8 bit values represent register values for individual pixels, and will generally be kept in FAST ram. The 'wid' and 'high' parameters indicate both the size of the 8 bit pixel data area, and the amount of data to render. The HamePort and the 'x' and 'y' parameters indicate where to place the rendered data. Note that the palette is not affected by this call. SEE ALSO: RETURNS: VOID HAME_Scroll( HamePort, dx, dy, x1, y1, x2, y2) ---------------------------------------------- This routine scrolls the region of the screen delimited by (x1,y1)- (x2,y2) by the amounts indicated by dx and dy. The newly vacated areas of the screen are filled with the HamePorts current background color. SEE ALSO: RETURNS: VOID HAME_OpenFont( fontname, size ) ------------------------------- Opens the indicated font if it exists, and returns a HameFont pointer. The font must exist in the correct size, or the call will fail. Both normal and colorfonts are supported, but for correct colorfont operation, the ColorText program must be currently running. After opening the font, you can examine font->NColors to find out how many colors are in the font (minimum of two), and font->BaseLine to determine the baseline of the font you have opened. SEE ALSO: HAME_GetFontPallete HAME_SetFontPen HAME_Text HAME_MakeFTables HAME_QText HAME_CloseFont RETURNS: struct HameFont * HAME_GetFontPallete( HamePort, Font ) ------------------------------------- This call will stuff the HamePorts palette with the correct color values if the Font is a colorfont. The colors will be stuffed into the HamePorts pallete starting at the current Foreground color as defined By HAME_SetAPen. The number of colors in the pallete is returned. SEE ALSO: HAME_OpenFont HAME_SetFontPen HAME_Text HAME_MakeFTables HAME_QText HAME_CloseFont RETURNS: int HAME_SetFontPen( Font, color ) ------------------------------ Sets the font base color for the given font. All HAME_Text calls use the current Font pen to determine the color for single color fonts, and to replace the variable color in colorfonts. This font pen has no effect on text rendered by HAME_QText. SEE ALSO: HAME_OpenFont HAME_GetFontPallete HAME_Text HAME_MakeFTables HAME_QText HAME_CloseFont RETURNS: VOID HAME_Text(HamePort, Font, string, x, y ) ---------------------------------------- This renders the given string into the HamePort at position x,y using the given font. It returns the width in Hame pixels of the rendered text. SEE ALSO: HAME_OpenFont HAME_GetFontPallete HAME_SetFontPen HAME_MakeFTables HAME_QText HAME_CloseFont RETURNS: int HAME_MakeFTables( Font, basecolor ) ----------------------------------- You must call this routine if you intend to use the HAME_QText routine. This routine precalculates certain tables which allow the text to be rendered much faster than HAME_Text, but with certain minor but important restrictions. You supply a HameFont pointer and the basecolor to be used by the font. Any text subsequently rendered with QText will map into the palette starting at the given basecolor. As for the restrictions, they are currently: basecolor must be an exact multiple of sixteen the number of colors in the font must be 16 or less This routine WILL work with non colorfonts SEE ALSO: HAME_OpenFont HAME_GetFontPallete HAME_SetFontPen HAME_Text HAME_QText HAME_CloseFont RETURNS: VOID HAME_QText(HamePort, Font, string, x, y ) ----------------------------------------- This is a quick text rendering routine that uses the tables precalculated by HAME_MakeFTables. It takes the same arguments as HAME_Text, but suffers (benefits?) from the restrictions outlined under HAME_MakeFTables. Returns the width, in hame pixels, of the rendered text. SEE ALSO: HAME_OpenFont HAME_GetFontPallete HAME_SetFontPen HAME_Text HAME_MakeFTables HAME_CloseFont RETURNS: int HAME_CloseFont(Font) -------------------- Closes a HameFont. SEE ALSO: HAME_OpenFont HAME_GetFontPallete HAME_SetFontPen HAME_Text HAME_QText HAME_MakeFTables RETURNS: VOID HAME_AllocClip( Width, Height, MaskFlag ) ----------------------------------------- Allocates a clip structure and bitplane memory for a clip of the given size. If MaskFlag is 1, then an additional bitplane will be allocated for masked clip operations. SEE ALSO: HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: struct Clip * HAME_DisposeClip( clip ) ------------------------ This frees all memory associated with the given clip, including bitplane memory, mask memory and the clip structure itself. SEE ALSO: HAME_AllocClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: VOID HAME_GetClip( HamePort, x, y, width, height ) --------------------------------------------- Allocates a clip of the given width and height and fills it with data from position x,y of the given HamePort. No mask is created for the clip. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: struct Clip * HAME_PutClip( HamePort, clip, x, y ) ------------------------------------ Renders the clip data into the given HamePort at position x,y. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: VOID HAME_ReadClipPixel( clip, x, y ) -------------------------------- Reads and returns the 8 bit pixel value at position x,y of the given clip. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: int HAME_WriteClipPixel( clip, x, y, reg ) -------------------------------------- Writes the 8 bit pixel value 'reg' into position x,y of the given clip. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: VOID HAME_ReadMaskPixel( clip, x, y ) -------------------------------- Reads and returns the 1 bit pixel value at position x,y of the given clips mask. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: int HAME_WriteMaskPixel( clip, x, y, v ) ------------------------------------ Writes the 1 bit pixel value 'v' into position x,y of the given clip. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_AllocClipMask HAME_DisposeClipMask HAME_MakeClipMask RETURNS: VOID HAME_AllocClipMask( clip ) -------------------------- Allocates a mask for the given clip. The mask will be the same width and height as the clip. This mask is already linked to the clip, but the Mask pointer itself is returned to let you know if the Allocation failed. If the pointer is NULL, you didn't get the mask. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_DisposeClipMask HAME_MakeClipMask RETURNS: UWORD * HAME_DisposeClipMask( clip ) ---------------------------- Frees the memory used by a clips mask. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_MakeClipMask RETURNS: VOID HAME_MakeClipMask( clip, transcolor ) ------------------------------------- Examines each pixel of the given clip, and sets the masks pixels accordingly. The 'transcolor' indicates what register value should be considered transparent. This mask will be used to restrict changes to the display to those areas of the screen where the mask is non-zero. SEE ALSO: HAME_AllocClip HAME_DisposeClip HAME_GetClip HAME_PutClip HAME_ReadClipPixel HAME_WriteClipPixel HAME_ReadMaskPixel HAME_WriteMaskPixel HAME_AllocClipMask HAME_DisposeClipMask RETURNS: VOID HAME_WaitScanline( HamePort, scanline ) --------------------------------------- POLLS the video beam pointer until it is past the scanline indicated. CAVEAT: THIS IS A BUSY WAIT LOOP SEE ALSO: RETURNS: VOID HAME_LockLayer( HamePort ) -------------------------- Locks all intuition layers from drawing into the screen this HamePort was opened on. In practical terms, this prevents the library routines (most of which write directly into bitplane memory) from trashing Intuition rendered items such as menus. When this call returns, you are free to render directly into the screens bitplanes without fear of the user pulling down a menu into which your data will be rendered. You *MUST* call this routine before you call HAME_WritePixel. SEE ALSO: HAME_WritePixel HAME_LockLayer. RETURNS: VOID HAME_UnlockLayer( HamePort ) ---------------------------- Allows intuition (or other well behaved routines) to write into the screen that the HamePort was opened on. You *MUST* call this routine after you are finished using the HAME_WritePixel function. SEE ALSO: HAME_WritePixel HAME_LockLayer. RETURNS: VOID /**/