HPGCC3 Documentation 3.0 R003

ggl.h File Reference

Extended grayscale graphics routines for HP calculators. More...

Go to the source code of this file.

Data Structures

struct  gglsurface
 A surface (bitmap) that can be drawn upon using GGL. More...

Defines

#define GGL_H_
#define STATEBUFSIZE   ((11+6)*4)
 The minimum number of bytes for a state buffer.
#define LCD_H   80
 Height of the screen, in pixels.
#define LCD_W   160
 Width of the screen, in pixels.
#define SCREENBUFSIZE   ((LCD_W>>2)*(LCD_H)*2)
 Number of bytes in the screen buffer.
#define ggl_setmode(framebuf)   sys_lcdsetmode(MODE_16GRAY,framebuf);
 Sets a 16-color display mode.
#define ggl_save(buf)   sys_lcdsave(buf)
 Saves the state of the LCD controller.
#define ggl_restore(buf)   sys_lcdrestore(buf)
 Restores the state of the LCD controller.
#define ggl_bitbltmask(dest, src, width, height, tcol)   ggl_bitbltoper(dest,src,width,height,tcol,&ggl_opmask)
 Copies a rectangular surface with mask.

Typedefs

typedef unsigned int(* gglfilter )(unsigned int pixels, int param)
 A filter for pixels being drawn to a surface.
typedef unsigned int(* ggloperator )(unsigned int dest, unsigned int source, int param)
 An operator for pixels being drawn to a surface.

Functions

void ggl_initscr (gglsurface *srf)
 Prepares to draw on the LCD screen with GGL.
void ggl_freescr ()
void ggl_gethpgscreen (gglsurface *srf)
 Prepares to draw on the LCD screen with GGL and HPG.
void ggl_show (int *buffer)
void ggl_pltnib (int *buff, int off, int color)
 Pokes a color into a specific pixel of a surface.
int ggl_getnib (int *buff, int off)
 Peeks a color from a specific pixel of a surface.
void ggl_hline (gglsurface *srf, int y, int xl, int xr, int color)
 Draws a horizontal line on a surface.
void ggl_vline (gglsurface *srf, int x, int yt, int yb, int color)
 Draws a vertical line on a surface.
void ggl_rect (gglsurface *srf, int x1, int y1, int x2, int y2, int color)
 Draws a rectangle on a surface.
void ggl_rectp (gglsurface *srf, int x1, int y1, int x2, int y2, int *color)
 Draws a rectangle on a surface with a 2D pattern.
void ggl_bitblt (gglsurface *dest, gglsurface *src, int width, int height)
 Copies a rectangular surface. Forward direction.
void ggl_revblt (gglsurface *dest, gglsurface *src, int width, int height)
 Copies a rectangular surface. Reverse direction.
void ggl_ovlblt (gglsurface *dest, gglsurface *src, int width, int height)
 Copies a rectangular surface. Safe to use when areas overlap.
void ggl_scrollup (gglsurface *dest, int width, int height, int npixels)
 Scroll a surface up.
void ggl_scrolldn (gglsurface *dest, int width, int height, int npixels)
 Scroll a surface down.
void ggl_scrolllf (gglsurface *dest, int width, int height, int npixels)
 Scroll a surface left.
void ggl_scrollrt (gglsurface *dest, int width, int height, int npixels)
 Scroll a surface right.
void ggl_filter (gglsurface *dest, int width, int height, int param, gglfilter filterfunc)
 Applies a filter to a surface.
void ggl_bitbltoper (gglsurface *dest, gglsurface *src, int width, int height, int param, ggloperator filterfunc)
 Applies a binary operator to a surface.
unsigned ggl_fltlighten (unsigned word, int param)
 Lightens an image.
unsigned ggl_fltdarken (unsigned word, int param)
 Darkens an image.
unsigned ggl_opmask (unsigned dest, unsigned src, int tcolor)
 Mask operator.
unsigned ggl_optransp (unsigned dest, unsigned src, int weight)
 Transparency blend operator.
int ggl_mkcolor (int color)
 Solid color word generator.
void ggl_mkcolor32 (int col32, int *pattern)
 30-colors dither pattern generator.
void ggl_initaline ()
 Antialiased lines initialization.
void ggl_aline (gglsurface *srf, int x1, int y1, int x2, int y2)
 Draw antialiased line.
void ggl_endaline ()
 Antialiased lines cleanup.

Detailed Description

Extended grayscale graphics routines for HP calculators.

Definition in file ggl.h.


Define Documentation

#define ggl_bitbltmask (   dest,
  src,
  width,
  height,
  tcol 
)    ggl_bitbltoper(dest,src,width,height,tcol,&ggl_opmask)

Copies a rectangular surface with mask.

Performs a bitblit copy operation where the given color is considered transparent, thus not affecting the background color. The direction of the memory movement is from top to bottom. Note: This is a macro that calls ggl_bitbltoper with the proper operator.

Parameters:
destThe surface to draw onto. The area will be copied at the coordinates x and y given in the proper fields of the gglsurface structure.
srcThe source surface. The region to copy will start at the coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to copy.
heightThe height in pixels of the rectangular region to copy.
tcolTransparent color. Color in the source surface to be considered as transparent (between 0 and 15).
See also:
ggl_bitblt
ggl_bitbltoper

Definition at line 496 of file ggl.h.

#define GGL_H_

Definition at line 16 of file ggl.h.

#define ggl_restore (   buf)    sys_lcdrestore(buf)

Restores the state of the LCD controller.

**OBSOLETE**: This function is now a macro that calls sys_lcdrestore().

Calling this function results in the current state of the LCD controller being restored from the given buffer. The buffer should have been filled in earlier by a call to ggl_save. Warning: A buffer with invalid or corrupted data might cause unexpected results, including possible damage to the LCD.

If HPG is in use, the application should use hpg_cleanup when finished to restore the LCD controller to a known state. It is dangerous to make changes to the LCD controller state while HPG is operating. However, it is safe to use ggl_save before initializing HPG and use ggl_restore after hpg_cleanup has returned.

Parameters:
bufA flat buffer, containing data stored by ggl_save.
See also:
ggl_save

Definition at line 254 of file ggl.h.

#define ggl_save (   buf)    sys_lcdsave(buf)

Saves the state of the LCD controller.

**OBSOLETE**: This function is now a macro that calls sys_lcdsave().

Calling this function results in the current state of the LCD controller being stored in the given buffer. The saved state can be restored by passing the same buffer to ggl_restore. This function can be used when it is important to restore the LCD controller to the exact previous state. For example, if a program sets the LCD in a non-standard (or unknown state, like when using hardware scrolling, and a routine needs to use the LCD, it can save the state and restore it later using ggl_save and ggl_restore.

If HPG is in use, the application should use hpg_cleanup when finished to restore the LCD controller to a known state. It is dangerous to make changes to the LCD controller state while HPG is operating. However, it is safe to use ggl_save before initializing HPG and use ggl_restore after hpg_cleanup has returned.

Parameters:
bufA flat buffer, with a size of at least STATEBUFSIZE bytes.
See also:
ggl_restore

Definition at line 232 of file ggl.h.

#define ggl_setmode (   framebuf)    sys_lcdsetmode(MODE_16GRAY,framebuf);

Sets a 16-color display mode.

This macro calls sys_lcdsetmode(), which actually switches the calculator LCD controller into 16-color grayscale mode with the given address for a frame buffer. This should be done for stand-alone GGL applications. (HPG applications using GGL should instead use HPG's hpg_set_mode_gray16 to perform the same task.)

Parameters:
framebufA pointer to the new LCD screen's frame buffer. This is generally found in the gglsurface::addr field of the surface passed to ggl_initscr or ggl_gethpgscreen. IMPORTANT: framebuf MUST be a physical memory pointer. Use sys_map_v2p() to convert.

Definition at line 207 of file ggl.h.

#define LCD_H   80

Height of the screen, in pixels.

Definition at line 63 of file ggl.h.

#define LCD_W   160

Width of the screen, in pixels.

Definition at line 68 of file ggl.h.

#define SCREENBUFSIZE   ((LCD_W>>2)*(LCD_H)*2)

Number of bytes in the screen buffer.

This constant provides the size in bytes of the screen buffer, allowing the use of standard routines like memset to clear the screen, memcpy to copy it elsewhere, and so forth.

Definition at line 78 of file ggl.h.

#define STATEBUFSIZE   ((11+6)*4)

The minimum number of bytes for a state buffer.

Save buffers, which are allocated and supplied to GGL by the application for use by ggl_save and ggl_restore, need to be at least this size to prevent undefined (but probably bad) behavior from occurring.

See also:
ggl_save
ggl_restore

Definition at line 58 of file ggl.h.


Typedef Documentation

typedef unsigned int(* gglfilter)(unsigned int pixels, int param)

A filter for pixels being drawn to a surface.

A filter is a unary operation (uses one argument) that is applied to colors being drawn to a screen. Filters are very flexible and can be used for a wide variety of drawing purposes, including color modification and texturing. However, they lack the ability to combine colors with those already on the surface. The function takes as arguments a word containing 8 pixels and a parameter defined by the user. A custom filter should process the 8 pixels, using the parameter if needed, and return a word containing the modified 8 pixels. Packs of 8 pixels are processed at the same time for efficiency reasons. Examples of simple filter operations are to 'darken' or 'lighten' an image. A more complex filter can be written for 'color replace' for example.

See also:
ggl_fltdarken
ggl_fltlighten
ggloperator

Definition at line 129 of file ggl.h.

typedef unsigned int(* ggloperator)(unsigned int dest, unsigned int source, int param)

An operator for pixels being drawn to a surface.

An operator is a binary operation (using two values) that is applied to colors being drawn to a screen. Operators can be used to implement a great variety of features, including either partial or complete transparency. Operators are more powerful than filters, but at a slightly higher performance cost. The function takes a word containing 8 pixels from the source surface, a word conatining the corresponding 8 pixels from the destination surface, and an arbitrary parameter. Packs of 8 pixels are processed at the same time for efficiency reasons. The function should return a word containing the 8 pixels resulting from the operation performed.

See also:
ggl_opmask
ggl_optransp
gglfilter

Definition at line 150 of file ggl.h.


Function Documentation

void ggl_aline ( gglsurface srf,
int  x1,
int  y1,
int  x2,
int  y2 
)

Draw antialiased line.

Draws a 3-pixel wide line with soft borders. Line is black on white. Call ggl_initaline before using this function.

Parameters:
srfSurface to draw onto.
x1X coordinate, origin of the line
y1Y coordinate, origin of the line
x2X coordinate, end of the line
y2Y coordinate, end of the line
See also:
ggl_initaline
ggl_endaline
void ggl_bitblt ( gglsurface dest,
gglsurface src,
int  width,
int  height 
)

Copies a rectangular surface. Forward direction.

Copies a rectangular area from one surface to another. The direction of memory movement is from top to bottom, so care should be taken if the areas overlap.

Parameters:
destThe surface to draw onto. The area will be copied at the coordinates x and y given in the proper fields of the gglsurface structure.
srcThe source surface. The region to copy will start at the coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to copy.
heightThe height in pixels of the rectangular region to copy.
See also:
ggl_revblt
ggl_ovlblt
void ggl_bitbltoper ( gglsurface dest,
gglsurface src,
int  width,
int  height,
int  param,
ggloperator  filterfunc 
)

Applies a binary operator to a surface.

Applies a user-defined operator on a specified region of a surface, using a second surface as an argument.

Parameters:
destThe surface to operate on. The area starts at coordinates x and y given in the proper fields of the gglsurface structure.
srcThe source surface. The area starts at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region.
heightThe height in pixels of the rectangular region.
paramA parameter to be passed to the operator. This parameter is defined by each operator function.
filterfuncThe operator function to apply.
See also:
ggloperator
ggl_filter
void ggl_endaline ( )

Antialiased lines cleanup.

Call this function after using antialiased lines. Call ggl_initaline for initialization.

See also:
ggl_initaline
ggl_aline
void ggl_filter ( gglsurface dest,
int  width,
int  height,
int  param,
gglfilter  filterfunc 
)

Applies a filter to a surface.

Applies a user-defined filter (unary operator) on a specified region of a surface.

Parameters:
destThe surface to filter. The area to filter starts at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to filter.
heightThe height in pixels of the rectangular region to filter.
paramA parameter to be passed to the filter. This parameter is defined by each filter function.
filterfuncThe filter function to apply.
See also:
gglfilter
ggl_bitbltoper
unsigned ggl_fltdarken ( unsigned  word,
int  param 
)

Darkens an image.

This filter darkens an image by adding the parameter to all the pixels. Do NOT call this function. This is a filter function to be passed as argument to ggl_filter.

See also:
ggl_filter
gglfilter
ggl_fltlighten
unsigned ggl_fltlighten ( unsigned  word,
int  param 
)

Lightens an image.

This filter lightens an image by subtracting the parameter from all the pixels. Do NOT call this function. This is a filter function to be passed as argument to ggl_filter.

See also:
ggl_filter
gglfilter
ggl_fltdarken
void ggl_freescr ( )

Free the buffer allocated by ggl_initscr().

void ggl_gethpgscreen ( gglsurface srf)

Prepares to draw on the LCD screen with GGL and HPG.

This routine prepares for GGL drawing onto an HPG surface. It fills in the gglsurface structure with appropriate values to draw to HPG's standard screen. This function should be called by HPG applications that wish to make use of GGL. Stand-alone GGL applications should use ggl_initscr instead.

Parameters:
srfAn instance of gglsurface to fill in with HPG's screen.
int ggl_getnib ( int *  buff,
int  off 
)

Peeks a color from a specific pixel of a surface.

Retrieves the color of the given pixel. The pixel is identified by an offset from the beginning of the frame buffer, which is defined as x + y * width for a given x and y coordinate, where width is the width of the surface to plot to. The calling procedure is responsible for correctly calculating the offset. This reduces the overhead when pixels are painted in a specific sequence.

Parameters:
buffThe address of a surface bitmap (gglsurface::addr field).
offThe offset (x + width * y).
Returns:
The color, between 0 and 15.
void ggl_hline ( gglsurface srf,
int  y,
int  xl,
int  xr,
int  color 
)

Draws a horizontal line on a surface.

Draws a horizontal line onto the given surface, in the given color or color pattern.

Parameters:
srfThe surface to draw onto.
yThe Y coordinate of the line.
xlThe left-most x coordinate of the line.
xrThe right-most x coordinate of the line.
colorThe color pattern. This is a 32-bit value, containing 8 consecutive pixels worth of color. For solid colors, set the color to contain the same pattern on every nibble (for color 8, use 0x88888888), or call ggl_mkcolor for that purpose. The colors in this pattern will be used consecutively in the horizontal direction. Patterns are always 8-pixel aligned, so painting a sequence of lines produces the right pattern.
void ggl_initaline ( )

Antialiased lines initialization.

Call this function before using antialiased lines. Call ggl_endaline for cleanup procedures when done.

See also:
ggl_aline
ggl_endaline
void ggl_initscr ( gglsurface srf)

Prepares to draw on the LCD screen with GGL.

This routine prepares for GGL drawing onto the LCD screen, by allocating memory for the screen buffer and filling the gglsurface structure with the proper width and other parameters. It is used by stand-alone GGL applications; HPG applications that make use of GGL should use ggl_gethpgscreen instead.

Parameters:
srfAn instance of gglsurface to fill in with the new surface.
int ggl_mkcolor ( int  color)

Solid color word generator.

Generates a word containing the specified color in every nibble, to be used with the line and rectangle functions.

Parameters:
colorColor between 0 and 15.
See also:
ggl_mkcolor32

Referenced by gControl::SolidColor().

void ggl_mkcolor32 ( int  col32,
int *  pattern 
)

30-colors dither pattern generator.

Generates an 8x8 pattern containing the specified color. The color is specified in a 30-colors scale. This function will return the appropriate dither pattern to approximate the color.

Parameters:
col32Color between 0 and 30, 0 being white and 30 being black.
patternPointer to and array of 8 words to be filled with the generated pattern.
See also:
ggl_mkcolor
unsigned ggl_opmask ( unsigned  dest,
unsigned  src,
int  tcolor 
)

Mask operator.

This operator copies the source image on the destination. All pixels in the source surface matching the color passed as param are not copied. Do NOT call this function. This is an operator function to be passed as argument to ggl_bitbltoper. The macro ggl_bitbltmask uses this operator.

See also:
ggl_bitbltoper
ggloperator
ggl_bitbltmask
unsigned ggl_optransp ( unsigned  dest,
unsigned  src,
int  weight 
)

Transparency blend operator.

This operator copies the source image on the destination with a uniform transparency, specified by the parameter. When parameter is 0, the source surface is opaque. When param is 16 the source surface is fully transparent. Intermediate values provide different opacities. Do NOT call this function. This is an operator function to be passed as argument to ggl_bitbltoper.

See also:
ggl_bitbltoper
ggloperator
void ggl_ovlblt ( gglsurface dest,
gglsurface src,
int  width,
int  height 
)

Copies a rectangular surface. Safe to use when areas overlap.

Copies a rectangular area from one surface to another. If the areas overlap, it chooses the appropriate direction and calls ggl_bitblt or ggl_revblt as needed.

Parameters:
destThe surface to draw onto. The area will be copied at the coordinates x and y given in the proper fields of the gglsurface structure.
srcThe source surface. The region to copy will start at the coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to copy.
heightThe height in pixels of the rectangular region to copy.
See also:
ggl_bitblt
ggl_revblt
void ggl_pltnib ( int *  buff,
int  off,
int  color 
)

Pokes a color into a specific pixel of a surface.

Colors the given pixel by the given color. The pixel is identified by an offset from the beginning of the frame buffer, which is defined as x + y * width for a given x and y coordinate, where width is the width of the surface to plot to. The calling procedure is responsible for correctly calculating the offset. This reduces the overhead when pixels are painted in a specific sequence.

Parameters:
buffThe address of a surface bitmap (gglsurface::addr field).
offThe offset (x + width * y).
colorThe color, between 0 and 15. 15=black.
void ggl_rect ( gglsurface srf,
int  x1,
int  y1,
int  x2,
int  y2,
int  color 
)

Draws a rectangle on a surface.

Fills in a rectangle onto the given surface, with the given color or color pattern. The color pattern is oriented horizontally, so that the color remains the same in any given column of pixels.

Parameters:
srfThe surface to draw onto.
x1The X coordinate of the top-left coordinate of the rectangle.
y1The Y coordinate of the top-left coordinate of the rectangle.
x2The X coordinate of the bottom-right coordinate of the rectangle.
y2The Y coordinate of the bottom-right coordinate of the rectangle.
colorThe color pattern. This is a 32-bit value, containing 8 consecutive pixels worth of color. For solid colors, set the color to contain the same pattern on every nibble (for color 8, use 0x88888888), or call ggl_mkcolor for that purpose. The colors in this pattern will be used consecutively in the horizontal direction.
void ggl_rectp ( gglsurface srf,
int  x1,
int  y1,
int  x2,
int  y2,
int *  color 
)

Draws a rectangle on a surface with a 2D pattern.

Fills in a rectangle onto the given surface, with the given color or color pattern. The color pattern is 8x8 pixels in size, and is repeated both horizontally and vertically.

Parameters:
srfThe surface to draw onto.
x1The X coordinate of the top-left coordinate of the rectangle.
y1The Y coordinate of the top-left coordinate of the rectangle.
x2The X coordinate of the bottom-right coordinate of the rectangle.
y2The Y coordinate of the bottom-right coordinate of the rectangle.
colorThe color pattern. This is an array of 8 32-bit values, each containing 8 consecutive pixels worth of color for a single line. The result is an 8x8 color pattern that is used to draw to the screen.
void ggl_revblt ( gglsurface dest,
gglsurface src,
int  width,
int  height 
)

Copies a rectangular surface. Reverse direction.

Copies a rectangular area from one surface to another. The direction of memory movement is from bottom to top, so care should be taken if the areas overlap.

Parameters:
destThe surface to draw onto. The area will be copied at the coordinates x and y given in the proper fields of the gglsurface structure.
srcThe source surface. The region to copy will start at the coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to copy.
heightThe height in pixels of the rectangular region to copy.
See also:
ggl_bitblt
ggl_ovlblt
void ggl_scrolldn ( gglsurface dest,
int  width,
int  height,
int  npixels 
)

Scroll a surface down.

Scrolls down a surface by the specified number of pixels. The unveiled area is not cleared.

Parameters:
destThe surface to draw onto. The area will be scrolled at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to scroll.
heightThe height in pixels of the rectangular region to scroll.
npixelsNumber of pixels to scroll.
See also:
ggl_scrollup
ggl_scrolllf
ggl_scrollrt
void ggl_scrolllf ( gglsurface dest,
int  width,
int  height,
int  npixels 
)

Scroll a surface left.

Scrolls left a surface by the specified number of pixels. The unveiled area is not cleared.

Parameters:
destThe surface to draw onto. The area will be scrolled at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to scroll.
heightThe height in pixels of the rectangular region to scroll.
npixelsNumber of pixels to scroll.
See also:
ggl_scrollup
ggl_scrolldn
ggl_scrollrt
void ggl_scrollrt ( gglsurface dest,
int  width,
int  height,
int  npixels 
)

Scroll a surface right.

Scrolls right a surface by the specified number of pixels. The unveiled area is not cleared.

Parameters:
destThe surface to draw onto. The area will be scrolled at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to scroll.
heightThe height in pixels of the rectangular region to scroll.
npixelsNumber of pixels to scroll.
See also:
ggl_scrollup
ggl_scrolldn
ggl_scrolllf
void ggl_scrollup ( gglsurface dest,
int  width,
int  height,
int  npixels 
)

Scroll a surface up.

Scrolls up a surface by the specified number of pixels. The unveiled area is not cleared.

Parameters:
destThe surface to draw onto. The area will be scrolled at coordinates x and y given in the proper fields of the gglsurface structure.
widthThe width in pixels of the rectangular region to scroll.
heightThe height in pixels of the rectangular region to scroll.
npixelsNumber of pixels to scroll.
See also:
ggl_scrolldn
ggl_scrolllf
ggl_scrollrt
void ggl_show ( int *  buffer)
void ggl_vline ( gglsurface srf,
int  x,
int  yt,
int  yb,
int  color 
)

Draws a vertical line on a surface.

Draws a vertical line onto the given surface, in the given color or color pattern.

Parameters:
srfThe surface to draw onto.
xThe x coordinate of the line.
ytThe top-most y coordinate of the line.
ybThe bottom-most y coordinate of the line.
colorThe color pattern. This is a 32-bit value, containing 8 consecutive pixels worth of color. For solid colors, set the color to contain the same pattern on every nibble (for color 8, use 0x88888888), or call ggl_mkcolor for that purpose. The colors in this pattern will be used consecutively in the vertical direction, making this different from the use of the color parameter in other GGL functions. Pattern is always 8-pixel aligned.