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
Wrap
Text File
|
1991-05-05
|
23KB
|
821 lines
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
/**/