HPG Graphics Library

1.0

Overview

HPG implements basic graphics functionality on the calculator display. Its features include:

Quick Start

A simple graphics program written with HPG should perform several tasks:

Quick Start Sample

On the theory that it is best to learn by immersion, here are two quick samples of using the HPG library. The first sample is a simple "Hello, world!" application.

 #include <hpgcc49.h>
 #include <hpgraphics.h>
 
 int main(void)
 {
     hpg_clear();
     hpg_draw_text("Hello, world!", 0, 0);
     while(!keyb_isON());
 
     return 0;
 }

Next is a more involved sample, demonstrating each of the steps from the list above. You may find it helpful to refer to this example as each step is explained below. This sample uses 16-color grayscale, a non-default font, and double-buffering.

 #include <hpgcc49.h>
 #include <hpgraphics.h>
 int main(void)
 {
     hpg_set_mode_gray16(1);
 
     hpg_set_font(hpg_stdscreen, hpg_get_bigfont());
     hpg_set_color(hpg_stdscreen, HPG_COLOR_GRAY_10);
 
     hpg_clear();
     hpg_draw_text("Hello, world!", 0, 0);
 
     hpg_flip(); //updates the screen with the new image (needed in double-buffered mode)
     while(!keyb_isON());
 
     return 0;
 }

Here is a program that draws some lines, text and shapes to the screen.

 #include <hpgcc49.h>
 #include <hpgraphics.h>
 
 int main(void){
    hpg_set_mode_gray16(1); //enter 16 colour, double buffered mode
    hpg_clear(); //clear the screen
    hpg_set_color(hpg_stdscreen, HPG_COLOR_BLACK);
    hpg_draw_text("minifont", 0, 0);
    hpg_set_font(hpg_stdscreen, hpg_get_bigfont()); //change to a big font
    hpg_draw_text("big font", 0, 20);
    hpg_set_font(hpg_stdscreen, hpg_get_minifont()); //and back to small
    hpg_draw_text("minifont again", 0, 35);
    hpg_draw_line(70,5,70,25);// draw a line
    hpg_draw_rect(50,60,55,70); //and a rectangle
    hpg_set_color(hpg_stdscreen, HPG_COLOR_GRAY_8); //grey    
    hpg_fill_rect(50,0,60,10); //fill in a rectangle
    hpg_set_color(hpg_stdscreen, HPG_COLOR_GRAY_5); //lightish grey
    hpg_fill_circle(70,70,4); //draw a circle
    hpg_flip(); //updates the screen with the new image (needed in double-buffered mode)
    while(!keyb_isON()); //wait until ON pressed
 }

Setting a Display Mode

The HPG library implements provides three different display modes for the calculator display. They are:

HPG defaults to using a single-buffered monochrome screen. If this is the screen you want, then you may skip this step.

After choosing a display mode, you should call one of hpg_set_mode_mono, hpg_set_mode_gray4, or hpg_set_mode_gray16. Each of these functions accepts one additional parameter, which will enable double-buffering if it is set.

When double buffering is enabled, your images are drawn to an off-screen buffer, and diplayed as a single action when the hpg_flip function is called. Until that time, the display will show the previous completed screen in its entirety. This prevents your users from viewing partially drawn screens, and can prevent an appearance of "flicker". HPG's implementation of double-buffering uses a combination of vsync and hardware page flipping to ensure that only complete frames are drawn.

Regardless of the current display mode, the HPG library provides a choice of 256 virtual colors. However, these colors are mapped in a mode-specific manner to the colors of the physical screen. In 1-bpp monochrome mode, for example, colors 0-127 appear as white, while colors 128-255 appear as black. By contrast, 16-color grayscale mode displays only colors 0-15 as white, and 240-255 as black, while the intermediate colors appear as shades of gray.

Configuring the Graphics Context

HPG defines a global variable, hpg_stdscreen, to refer to the screen's graphics context. This graphics context defines several properties that affect how drawing operations modify the screen. These include:

Before drawing, you may modify any of these attributes. The library defaults to drawing in paint mode, black, the minifont, and a solid fill. These defaults may be modified by using the following functions:

More information about these options may be found in the reference documentation.

Drawing to the Graphics Context

HPG provides a number of functions to draw to a graphics context. These include any functions that begin with hpg_draw_ or hpg_fill_ prefixes. You may browse the reference documentation for more information on each of these functions.

The hpg_clear function is used to clear the screen. The initial contents of the screen are undefined, and it is recommended that you clear the screen prior to beginning your drawing.

Displaying a New Graphics Image

If you chose a single-buffered display mode, your drawing operations are already visible on the screen. If you chose a double-buffered mode, however, then your changes to the screen are not yet visible. You need to inform the library that you are done drawing, so it can display the completed image to the screen. This is done by calling hpg_flip.

Cleaning Up the Display

The display needs to be restored to a very specific state prior to exiting your application. HPG provides a method called hpg_cleanup to do this.

Attention:
All applications which use HPG should call hpg_cleanup just prior to exiting, after the last call to any other HPG function.
And that's all there is to it!

General Information

Screen Coordinates

The HP49G+ screen is 131 by 80 pixels in size. The coordinate system of HPG is a standard screen coordinate plane (which is inverted in the Y dimension from a standard mathematical 2D coordinate plane). The pixel at coordinate (0, 0) is in the upper-left of the screen. X coordinates increase to the right, and Y coordinates increase toward the bottom. The lower-right pixel of the screen is (130, 79).

Clipping Regions

Drawing operations in HPG may be clipped to subregions of the screen. The three functions used for this purpose are hpg_clip, hpg_clip_set, and hpg_clip_reset. All clipping regions in HPG are axis-aligned rectangles. By default, drawing operations are clipped to the size of the screen.

Off-screen Images

Occasionally, it is useful to draw temporarily to an off-screen area, which can be copied to the screen on demand. HPG uses images to provide this functionality.

An image is created by calling any of hpg_alloc_mono_image, hpg_alloc_gray4_image, or hpg_alloc_gray16_image. The size of the image is passed as parameters to the function. Images can be arbitrary size, limited by available memory. The result of the allocation function is a pointer to an hpg_t, which can be used with drawing function in the normal manner. You will need to use functions with the _on suffix, as opposed to those that draw directly to the screen.

Note:
Newly allocated images have undefined contents. You should ensure that you either use hpg_clear_on to clear any old contents prior to drawing, or guarantee that your drawing code overwrites every pixel of the screen. Failure to do so can result in garbage data within the image, which may be later copied to the screen.
When you wish to copy a portion of the image to the screen, the hpg_blit function can accomplish this task.

Xpm Image Loading

Preliminary code exists to load Xpm image files from a file on disk. The steps required to do so may be unusual to programmers who have not worked with C-compilable file formats before. Here is a sample of loading and drawing an Xpm file to the screen:

 #include "monalisa.xpm"

 int main(void)
 {
     hpg_set_mode_gray16(0);
     hpg_t *img = hpg_load_xpm_gray16(monalisa_xpm);

     hpg_blit(img, 0, 0, 80, 80, hpg_stdscreen, 0, 0);

     while(!keyb_isON());
     hpg_free_image(img);

     return 0;
 }

The first line of the example above includes the image file into the application code. Unlike most image formats, Xpm files consist of C code that can be compiled. This C code declares a data structure called <name>_xpm, which contains the image data. The data is then loaded into an off-screen image, and drawn to the screen.


Generated on Fri Feb 16 16:43:17 2007 for hpg by  doxygen 1.5.0