Creating a Cursor

This section discusses the following aspects of cursors:

• Introduction to Cursors
• Defining a New Cursor
• Cross-Hair Cursor
• Cursor Subroutines

List of GL Cursor Subroutines

Introduction to Cursors

The cursor is handled with special cursor hardware. As the color guns scan the screen and cross the square region of the screen where the cursor is to be drawn, they look at the corresponding position in the cursor mask to see what color to draw.

The cursor mask can be 1 or 2 bits deep. If the cursor mask is 0, the normal color is presented. If the mask is nonzero, the mask value is looked up in a color table (very similar to overlay) to find out what color to draw. The cursor color takes precedence over the overlay color. As with overlays, if the cursor mask is 1 bit deep, there is only one possible color. If the cursor mask is 2 bits deep, the cursor can have up to three colors.

The system supports five different cursor types: a 16-by-16-bit cursor in one or three colors; a 32-by-32-bit cursor in one or three colors; and a cross-hair, one-color cursor. To specify a cursor completely, you need to specify not only its type, but also its shape and colors. In addition, every cursor has an origin, or hot spot, and can be turned on or off. See the Sample Cursors figure for examples of a 16-by-16-bit one-color cursor.

Cursor number zero (0), the default cursor, is an arrow pointing to the upper left corner of the cursor glyph; its origin is at (0, 15), the tip of the arrow. The default cursor cannot be redefined and can always be used. The position of the origin of the cursor is set to the current values of the valuators that are attached to the cursor.

Defining a New Cursor

To define and use a new cursor, you must follow these steps:

1. Enable or disable the visibility of the cursor with the curson/cursoff subroutines.
2. Set the cursor type to one of the five allowable types with the curstype subroutine.
3. Define the cursor's shape and assign it a number with the defcursor subroutine.
4. If necessary, define its origin (or hot spot) with the curorigin subroutine, and its colors with the drawmode and mapcolor subroutines.
5. Finally, the new cursor becomes the current cursor with a call to the setcursor subroutine.

The following figure illustrates various types of cursors.

If an application needs a number of different cursors, it typically defines all of them on initialization, and then switches from one to another using the setcursor (and perhaps. the mapcolor) subroutine. Although they do not physically do so, cursors can be thought of as occupying one or two bitplanes of their own, which behave like overlay bitplanes as described previously.

A one-color cursor uses one bitplane and a three-color cursor occupies two. Where there are zeros in the cursor's bitplanes, the contents of the standard, overlay, and underlay bitplanes appear. In the same way that overlay colors are defined, the drawmode and mapcolor subroutines define the cursor's colors. For example, call the following for a one-color cursor:

drawmode(CURSORDRAW);

mapcolor(1, r, g, b);

Or, call the following for a three-color cursor:

mapcolor(1, r1, g1, b1);
mapcolor(2, r2, g2, b2);
mapcolor(3, r3, g3, b3);

When the cursor pattern contains a 1(=01), the color value (r1, g1, b1) is presented. When the cursor pattern is 2(=10), the color value (r2, g2, b2) appears, and so on. Be sure, after you have defined the cursor's colors, to call:

drawmode(NORMALDRAW)

Cross-Hair Cursor

The cross-hair cursor is formed with two 1-pixel-wide, intersecting lines, one horizontal and one vertical that extend completely across the screen. Its origin is at the intersection of the two lines. This one-color cursor always uses cursor color 3 as its color. The color of the cross-hair cursor is set by mapping color index 1.

The cross-hair cursor consists of a default glyph that cannot be changed. If you assign a value to it with the defcursor subroutine, the user-defined glyph is ignored. The cross-hair cursor does not work if more than one window is open.

Cursor Subroutines

The following GL subroutines control cursors.

curson and cursoff Subroutines

The curson and cursoff subroutines turn the cursor visibility on and off, respectively. However, they execute fairly slowly and should not be heavily used. These subroutines control only the visibility of the cursor and do not disable or enable the cursor or mouse-button click events inside the current window. The curson subroutine is the default. The syntax for the curson and cursoff subroutines is as follows:

void curson()

void cursoff()

GL formerly required the cursor to be turned off before any drawing was attempted and turned on again after drawing was completed. This is no longer required. However, existing code that is being ported to the current release may often use this function. This code should be modified to remove these subroutines, or the subroutines should be effectively removed by using #ifdef with the C programming language preprocessor. If this is not done, performance will be adversely and severely affected.

curstype Subroutine

The curstype subroutine defines the current cursor type. The value given in the type parameter is C16X1, C16X2, C32X1, C32X2, or CCROSS. This value is used by the defcursor subroutine to determine the dimensions of the arrays that define the cursor's shape. The default value is C16x1. The CCROSS value indicates a predefined cross-hair cursor, which is one pixel wide. The hot spot is at the center of the cross. Its default center is (15, 15). The CCROSS value uses cursor color 3. The syntax is as follows:

void curstype(Int32 type)

After you call the curstype subroutine, call the defcursor subroutine to specify the appropriate-sized array and assign a numeric value to the cursor glyph.

defcursor Subroutine

The defcursor subroutine defines a cursor glyph. The index parameter is an index into the table of defined cursors, and the cursor parameter is an array of bits of the correct size, which depends on the current cursor type. The format of the array of bits is exactly the same as that for characters in a font. The 16-bit word at the lower-left of the cursor bitmap is given first, then (if the cursor is 32 bits wide) the word to its right. Continue in this way to the top of the cursor bitmap for either 16 or 64 words. If the cursor is three-colored, another set of 16 or 64 words follows (again beginning at the bottom) for the second plane of the mask. The syntax is as follows:

void defcursor(Int32 index, Uint16 *cursor)

curorigin Subroutine

The curorigin sets the origin of a cursor. The origin is the point on the cursor that aligns with the current cursor valuators. The lower-left corner of the cursor has coordinates (0,0). Before calling the curorigin subroutine, you must define the cursor with the defcursor subroutine. The index parameter is an index into the cursor table created by the defcursor subroutine. The curorigin subroutine does not take effect until there is a call to the setcursor subroutine. The syntax is as follows:

void curorigin(Int16 index, Int16 xorigin, Int16 yorigin)

setcursor Subroutine

The setcursor subroutine sets the cursor characteristics. It selects a cursor glyph from among those defined with the defcursor subroutine. The index parameter picks a glyph from the definition table. The color and writemask parameters are ignored. They are present for compatibility with older systems that still make use of them. Set the color for the cursor with the mapcolor and drawmode subroutines. The syntax is as follows:

void setcursor(Int16 index,
               Colorindex color, Colorindex writemask)

getcursor Subroutine

The getcursor subroutine returns the cursor characteristics. It returns two values: the cursor glyph (in the index parameter) and a Boolean value (in the bool parameter) indicating whether the cursor is visible.

Note: The color and writemask parameters are included for compatibility with previous versions; otherwise, they provide no useful information for current usage.

The syntax is as follows:

void getcursor(Int16 *index, Colorindex *color,
               Colorindex *writemask, Int32 *bool)

The default is the glyph index 0 in the cursor table, displayed with the color 1, drawn in the first available bitplane, and automatically updated on each vertical retrace.

The following example program defines a three-color, 32-by-32-bit cursor in the shape of an American flag with 12 stars:

#include <gl/gl.h>

main ()
{
    winopen("flag");
    setflag();
    color(0);
    clear();
    sleep(20);
}

setflag()
{
    static short        curs2[128] = {
        0,      0,      0,      0,
        0,      0,      0,      0,
        0,      0,      0,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff, 0xffff, 0xffff, 0xffff,
     0,     0xffff, 0x6666, 0xffff,
    0x6666, 0xffff,      0, 0xffff,
     0,     0xffff, 0x6666, 0xffff,
    0x6666, 0xffff,      0, 0xffff,
     0,     0xffff, 0x6666, 0xffff,
    0x6666, 0xffff,      0, 0xffff,

     0,      0,      0,      0,
     0,      0,      0,      0,
     0,      0,      0,      0,
     0,      0,      0,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
     0,      0,      0,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
     0,      0,      0,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
     0,      0,      0,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff,      0, 0xffff,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff,      0, 0xffff,      0,
    0xffff, 0xffff, 0xffff, 0xffff,
    0xffff,      0, 0xffff,      0 };

    curstype(C32X2);
    drawmode(CURSORDRAW);
    mapcolor(1,255,0,0);
    mapcolor(2,0,0,255);
    mapcolor(3,255,255,255);
    defcursor(1,curs2);
    setcursor(1,0,0);
    drawmode(NORMALDRAW);
}