Chapter 2. Creating Your First graPHIGS API Program

This section covers the following topics:

• Writing, Compiling, and Running the square Program
• Examining the square Program
  • Including the afmnc.h File
  • Initializing the graPHIGS API
  • Creating a Geometry Structure
  • Displaying the Structure
  • Exiting the Program

Writing, Compiling, and Running the square Program

Your first program is called square, since it puts a red square with a white border on the screen.

1. Enter the following program into a file called square.c (e.g., vi square.c ):

   (Ref #1.)

   /*
    * COMPONENT_NAME:  graPHIGS API Samples
    *
    * ORIGINS:  27
    *
    * (C) COPYRIGHT International Business Machines Corp. 1990
    * All Rights Reserved
    *
    * Licensed Materials - Property of IBM
    *
    * US Government Users Restricted Rights - Use, duplication or
    * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
    */
   /*---------------------------------------------------------------*/
   /* graPHIGS Start-Up :     our first program                     */
   #include <afmnc.h>
                         /* graPHIGS include file */
    
    main() {
     int wsid = 1, viewid = 0, strid = 1;
     int n4[1] = {4};
     int status,choice;
     static float pts[8] = {0.5,0.5, 0.5,-0.5, -0.5,-0.5, -0.5,0.5};
    
     GPOPPH ("        ",0);         /* open graPHIGS                */
     GPOPWS (wsid,"*","X       ");  /* open a workstation           */
    
     GPOPST(strid);         /* open structure                       */
     GPEF  (2);             /* set edge on                          */
     GPIS  (2);             /* set interior style solid             */
     GPICI (2);             /* set interior color RED               */
     GPECI (1);             /* set edge color WHITE                 */
     GPPG2 (1,n4,2,pts);    /* add 2D polygon                       */
     GPCLST();              /* close structure                      */
    
     GPARV (wsid,viewid,strid,1.0);    /* link root to view         */
     GPUPWS(wsid,2);                   /* update workstation        */
     GPRQCH(wsid,2,&status,&choice);   /* wait for mouse hit        */
     GPCLPH();                         /* close graPHIGS            */
   }
   -------------------------------------------------------------------

2. Compile the program using the following AIX command:

   cc -o square square.c -lgP

3. Run the program by entering:

   ./square

   A window pops onto the screen. Inside the window is a red square with a white border. To exit the program, place the mouse pointer, or locator input device, inside the graPHIGS API window and press any mouse button.

Examining the square Program

This section describes the purpose of various parts of the program:

Including the afmnc.h File

Every graPHIGS API program written in the C programming language must include the file afmnc.h. This file contains the entry point definitions for all graPHIGS API functions.

#include <afmnc.h>             /* graPHIGS include file */

Initializing the graPHIGS API

The following two lines are what actually initialize the graPHIGS API. The Open graPHIGS (GPOPPH) subroutine puts the graPHIGS API into the open state, and Open Workstation subroutine opens one graphics workstation with the specified workstation identifier, wsid.

----------------------------------------------------------------
GPOPPH ("        ",0);         /* open graPHIGS               */
GPOPWS (wsid,"*","X       ");  /* open a workstation          */
----------------------------------------------------------------

Creating a Geometry Structure

The next section of code creates a geometry structure with the specified structure identifier, strid. The actual geometry and attributes are placed inside this structure. In this case, polygon edge attributes and polygon interior attributes are inserted into the structure, followed by a 2D polygon.

----------------------------------------------------------------
GPOPST(strid);         /* open structure                      */
GPEF  (2);             /* set edge on                         */
GPIS  (2);             /* set interior style solid            */
GPICI (2);             /* set interior color RED              */
GPECI (1);             /* set edge color WHITE                */
GPPG2 (1,n4,2,pts);    /* add 2D polygon                      */
GPCLST();              /* close structure                     */
----------------------------------------------------------------

Displaying the Structure

The next two lines of code display the geometry on the screen. The geometry structure you just created must be associated with a workstation view before it can be displayed. The first line of code associates the structure (called a root structure) with the default graPHIGS API view 0, specified by the view identifier viewid. The second line of code tells the workstation to update itself using the Update Workstation (GPUPWS) subroutine.

----------------------------------------------------------------
GPARV (wsid,viewid,strid,1.0);   /* link root to view         */
GPUPWS(wsid,2);                  /* update workstation        */
----------------------------------------------------------------

Exiting the Program

The last two lines of code allow you to exit the program gracefully. The Request Choice (GPRQCH) subroutine tells the graPHIGS API to wait until a mouse button is pressed. Then, the Close graPHIGS (GPCLPH) subroutine closes the graPHIGS API and the program exits.

-----------------------------------------------------------------
GPRQCH(wsid,2,&status,&choice);  /* wait for mouse hit         */
GPCLPH();                        /* close graPHIGS             */
-----------------------------------------------------------------