HP OpenVMS Systems Documentation

1. After receiving notification that the server has mapped the window, the client writes two messages into the window. For information about using the DRAW IMAGE STRING routine, see Chapter 8.
2. If the user clicks MB1, the client draws rectangles defined in the initialization loop. If the user clicks MB2, the client exits the system. The client determines which button the user has clicked by referring to the button member of the button event data structure. For more information about the button event data structure, see Chapter 9.
3. The DRAW RECTANGLE routine has the following format:

   X$DRAW_RECTANGLES(display, drawable_id, gc_id, rectangles, num_rectangles)

Figure 6-8 Rectangles Drawn Using the DRAW RECTANGLES Routine

Xlib routines enable clients to draw either single or multiple arcs. To draw a single arc, use the DRAW ARC routine, specifying a rectangle that defines the boundaries of the arc and two angles that determine the start and extent of the arc, as in the following:

       PARAMETER X = 50, Y = 100,
       1     WIDTH = 25, LENGTH = 50,
       1     ANGLE1 = 5760, ANGLE2 = 5760
                         .
                         .
                         .
       CALL X$DRAW_ARC(DISPLAY, WINDOW, GC, X, Y, WIDTH, HEIGHT,
       1     ANGLE1, ANGLE2)

The server draws an arc within a rectangle. The client specifies the upper left corner of the rectangle, relative to the origin of the drawable. The center of the rectangle is the center of the arc. The width and height of the rectangle are the major and minor axes of the arc, respectively.

Two angles specify the start and extent of the arc. The angles are signed integers in degrees scaled up by 64. For example, a client would specify a 90-degree arc as 64*90 or 5760 . The start of the arc is specified by the first angle, relative to the three o'clock position from the center of the rectangle. The extent of the arc is specified by the second angle, relative to the start of the arc. Positive integers indicate counterclockwise motion; negative integers indicate clockwise motion.

To draw multiple arcs, use the following method:

1. Define an array of arc data structures.
2. Call the DRAW ARCS routine, specifying the array that defines the arcs and the number of array elements.

Figure 6-9 illustrates the arc data structure.

Figure 6-9 Arc Data Structure

This chapter describes how to work with off-screen graphics resources, including the following topics:

• Creating and freeing pixmaps
• Creating and managing bitmaps
• Working with images

A pixmap is an area of memory into which clients can either define an image or temporarily save part of a screen. Pixmaps are useful for defining cursors and icons, for creating tiling patterns, and for saving portions of a window that have been exposed. Additionally, drawing complicated graphics sequences into pixmaps and then copying the pixmaps to a window are often faster than drawing the sequences directly to a window.

Use the CREATE PIXMAP routine to create a pixmap. The routine creates a pixmap of a specified width, height, and depth. If the width or height is zero or the depth is not supported by the drawable root window, the server returns an error. The pixmap must be associated with a window, which can be either an input-output or an input-only window.

Example 7-1 illustrates creating a pixmap to use as a backing store for drawing the star of Example 6-5.

C    Create window WINDOW on display DPY, defined
C    as follows:
C         Position: x = 100,y = 100
C         Width = 600
C         Height = 600
C    GC refers to the graphics context

        INTEGER*4 PIXMAP
        INTEGER*4 EXPOSE_FLAG
                    .
                    .
                    .
C
C    Create graphics context
C

        GC_MASK = X$M_GC_FOREGROUND .OR. X$M_GC_BACKGROUND

(1)      XGCVL.X$L_GCVL_FOREGROUND =
        1   DEFINE_COLOR(DPY, SCREEN, VISUAL, 3)

        XGCVL.X$L_GCVL_BACKGROUND =
        1   DEFINE_COLOR(DPY, SCREEN, VISUAL, 3)

        GC = X$CREATE_GC(DPY, WINDOW, GC_MASK, XGCVL)
C
C    Create the pixmap
C
(2)      PIXMAP = X$CREATE_PIXMAP(DPY, WINDOW, WINDOW_W, WINDOW_H, DEPTH)
(3)      CALL X$FILL_RECTANGLE(DPY, PIXMAP, GC, 0, 0, WINDOW_W,
        1              WINDOW_H)
        CALL X$SET_FOREGROUND(DPY, GC, DEFINE_COLOR(DPY, SCREEN,
        1              VISUAL, 2))
(4)      CALL X$FILL_POLYGON(DPY, PIXMAP, GC, PT_ARR, 6, X$C_COMPLEX,
        1              X$C_COORD_MODE_ORIGIN)
                    .
                    .
                    .
C
C       Handle events
C
        DO WHILE (.TRUE.)

            CALL X$NEXT_EVENT(DPY, EVENT)

            IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1           150, 25, 'To create a filled polygon, click MB1')
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1           150, 75, 'To exit, click MB2')
(5)              IF (EXPOSE_FLAG .EQ. 0) THEN
                    EXPOSE_FLAG = 1
                ELSE
                    CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 0, 0,
        1               WINDOW_W, WINDOW_H, 0, 0)
                    CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1               150, 75, 'To exit, click MB2')
                END IF
            END IF

            IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND.
        1       EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN
                CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 0, 0,
        1           WINDOW_W, WINDOW_H, 0, 0)
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1           150, 75, 'To exit, click MB2')
            ENDIF

            IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND.
        1       EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN
                CALL SYS$EXIT(%VAL(1))
            END IF
        END DO

        END

1. Pixmaps use only the foreground member of the graphics context to define color. Because the client is using the pixmap as backing store, which is copied into the window to repaint exposed areas, both foreground and background members of the graphics context are first defined as the window background color.
2. The pixmap has the width, height, and depth of the window.
3. FILL RECTANGLE fills the pixmap with the background color of the window. After filling the pixmap to ensure that pixel values of both the pixmap and window background are the same, the foreground color is redefined for graphics operations.
4. After redefining foreground color, the client draws the polygon into the pixmap. For a description of specifying and filling the polygon, see Example 6-5.
5. At the first window exposure, the client draws only the text into the window. On subsequent exposures, the client copies the pixmap into the window to repaint exposed areas. For a description of handling exposure events, see Chapter 9.

Note that the CREATE PIXMAP routine is not a synchronous routine and does not return an error if the routine fails to create a pixmap. Although Xlib returns a resource ID for this routine, it does not indicate that a valid resource was created by the server. Refer to Section 9.13.3 for a method to check if a pixmap, or any X resource, has been created.

When a client no longer needs a pixmap, use the FREE PIXMAP routine to free storage associated with it. FREE PIXMAP first deletes the association between the pixmap identifier and the pixmap and then frees pixmap storage.

7.2 Creating and Managing Bitmaps

Xlib enables clients to create files of bitmap data and then to use those files to create either bitmaps or pixmaps. To create a bitmap data file, use the WRITE BITMAP FILE routine. Example 7-2 illustrates creating a pixmap and writing the pixmap data into a bitmap data file.

        PT_ARR(1).X$W_GPNT_X  = 20
        PT_ARR(1).X$W_GPNT_Y  = 0
        PT_ARR(2).X$W_GPNT_X  = 20
        PT_ARR(2).X$W_GPNT_Y  = 5
        PT_ARR(3).X$W_GPNT_X  = 20
        PT_ARR(3).X$W_GPNT_Y  = 10
        PT_ARR(4).X$W_GPNT_X  = 20
        PT_ARR(4).X$W_GPNT_Y  = 15
        PT_ARR(5).X$W_GPNT_X  = 20
        PT_ARR(5).X$W_GPNT_Y  = 20
                    .
                    .
                    .
C
C   Create the pixmap
C
        PIXMAP = X$CREATE_PIXMAP(DPY, WINDOW, PIX_WIDTH, PIX_HEIGHT,
        1     DEPTH)
        CALL X$FILL_RECTANGLE(DPY, PIXMAP, GC, 0, 0, PIX_WIDTH,
        1     PIX_HEIGHT)
        CALL X$SET_FOREGROUND(DPY, GC, DEFINE_COLOR(DPY, SCREEN,
        1     VISUAL, 2))
        CALL X$DRAW_LINES(DPY, PIXMAP, GC, PT_ARR, 5, X$C_COORD_MODE)
        STATUS = X$WRITE_BITMAP_FILE(DPY, 'BITFILE.DAT', PIXMAP,
        1     20, 20, 0, 0)

The client first creates a pixmap using the method described in Section 7.1 and then calls the WRITE BITMAP FILE routine to write the pixmap data into the BITFILE.DAT bitmap file.

To create a bitmap or pixmap from a bitmap data file, use either the CREATE BITMAP FROM DATA or CREATE PIXMAP FROM DATA routine. Example 7-3 illustrates creating a pixmap from the bitmap data stored in BITFILE.DAT.

                         .
                         .
                         .
        LOGICAL*1 LINES(60)

        PARAMETER PIX_WIDTH = 16, PIX_HEIGHT = 16

        DATA LINES /'AA'X, 'AA'X, '0A'X, '55'X, '55'X, '05'X,
        1       'AA'X, 'AA'X, '0A'X, '55'X, '55'X, '05'X, 'AA'X,
        1       'AA'X, '0A'X, '55'X, '55'X, '05'X, 'AA'X, 'AA'X,
        1       '0A'X, '55'X, '55'X, '05'X, 'AA'X, 'AA'X, '0A'X,
        1       '55'X, '55'X, '05'X, 'AA'X, 'AA'X, '0A'X, '55'X,
        1       '55'X, '05'X, 'AA'X, 'AA'X, '0A'X, '55'X, '55'X,
        1       '05'X, 'AA'X, 'AA'X, '0A'X, '55'X, '55'X, '05'X,
        1       'AA'X, 'AA'X, '0A'X, '55'X, '55'X, '05'X, 'AA'X,
        1       'AA'X, '0A'X, '55'X, '55'X, '05'X/
                         .
                         .
                         .

C
C    Create the pixmap
C

        PIX_FOREGROUND = XGCVL.X$L_GCVL_FOREGROUND
        PIX_BACKGROUND = XGCVL.X$L_GCVL_BACKGROUND
        PIXMAP = X$CREATE_PIX_FROM_BITMAP_DATA(DPY, WINDOW, LINES,
        1              PIX_WIDTH, PIX_HEIGHT, PIX_FOREGROUND,
        1              PIX_BACKGROUND, DEPTH)
        CALL X$SET_WINDOW_BACKGROUND_PIXMAP(DPY, WINDOW, PIXMAP)
                         .
                         .
                         .

The client uses the pixmap to define window background.

7.3 Working with Images

Instead of managing images directly, clients perform operations on them by using the image data structure, which includes a pointer to data such as the LINES array defined in Example 7-3. In addition to the image data, the image data structure includes pointers to client-defined functions that perform the following operations:

• Destroying an image
• Getting a pixel from the image
• Storing a pixel in the image
• Extracting part of the image
• Adding a constant to the image

If the client has not defined a function, the corresponding Xlib routine is called by default.

Figure 7-1 illustrates the data structure.

Figure 7-1 Image Data Structure

5643ximage_pic.tex

Table 7-1 describes the members of the data structure.

To create an image, use either the CREATE IMAGE or the GET IMAGE routine. CREATE IMAGE initializes an image data structure, including a reference to the image data. For example, the following call creates an image data structure that points to the image data LINES, illustrated in Example 7-3:

        RECORD /X$IMAGE/ IMAGE
                       .
                       .
                       .
        PARAMETER   WINDOW_W = 600, WINDOW_H = 600,
        1           PIX_WIDTH = 16, PIX_HEIGHT = 16,
        1           BITMAP_PAD 16, BYTES_PER_LINE 16
                       .
                       .
                       .
        STATUS = X$CREATE_IMAGE(DPY, VISUAL, DEPTH, X$C_Z_PIXMAP,
        1       0, LINES, PIX_WIDTH, PIX_HEIGHT, BITMAP_PAD,
        1       BYTES_PER_LINE, IMAGE)
        IF (STATUS .EQ. 0) THEN
            WRITE(6,*) 'Image not created!'
            CALL SYS$EXIT(%VAL(1))
        ENDIF
                       .
                       .
                       .

Note that the CREATE IMAGE routine does not allocate storage space for the image data.

To create an image from a drawable, use the GET IMAGE routine. In the following example, the client creates an image from a pixmap:

        PARAMETER   X_ORIGIN = 0, Y_ORIGIN = 0,
        1           PIX_WIDTH = 16, PIX_HEIGHT = 16
                         .
                         .
                         .
        IMAGE = X$GET_IMAGE(DPY, PIXMAP, X_ORIGIN, Y_ORIGIN,
        1 PIX_WIDTH, PIX_HEIGHT, XGCVL.X$L_GCVL_PLANE_MASK,
        1 X$C_Z_PIXMAP)
                         .
                         .
                         .

When the client calls the GET IMAGE routine and the drawable is a window, the window must be mapped. In addition, if there are no inferiors or overlapping windows, the specified rectangle of the window should be fully visible on the screen and wholly contained within the outside edges of the window. In other words, an error results if the GET IMAGE routine is called to get a portion of a window that is off-screen.

To transfer an image from memory to a drawable, use the PUT IMAGE routine. In the following example, the client transfers the image from memory to a window:

        PARAMETER  SRC_X = 0, SRC_Y = 0,
        1          DST_X = 200, DST_Y = 200,
        1          PIX_WIDTH = 16, PIX_HEIGHT = 16
                         .
                         .
                         .
        CALL X$PUT_IMAGE(DPY, WINDOW, GC, IMAGE, SRC_X, SRC_Y,
        1    DST_X, DST_Y, PIX_WIDTH, PIX_HEIGHT)
                         .
                         .
                         .

The call transfers the entire image, which was created in the call to GET IMAGE, from memory to coordinates (200, 200) in the window.

As the description of the image data structure indicates, Xlib enables clients to store an image in the following ways:

• As a bitmap---XY bitmap format stores the image as a two-dimensional array. Figure 7-2 illustrates XY bitmap format.
• As a set of bitmaps---XY pixmap format stores the image as a stack of bitmaps. Figure 7-3 illustrates XY pixmap format.
• As a list of pixel values---Z pixmap format stores the image as a list of pixel values viewed as a horizontal row. Each example of creating an image uses Z pixmap format. Figure 7-4 illustrates scanline order.

Figure 7-2 XY Bitmap Format

Figure 7-3 XY Pixmap Format

Figure 7-4 Z Format

Xlib includes routines to change images by manipulating their pixel values and creating new images out of subsections of existing images. Table 7-2 lists these routines and their use. Clients can override these routines by defining functions referred to in the image data structure.

When a client no longer needs an image, use the DESTROY IMAGE routine to deallocate memory associated with the image data structure.