Name

phigs − 3D graphics support

Synopsis

Digital UNIX
 cc -o application application.o -lPHIGSC
  ULTRIX
 cc -o application application.o -lPHIGSC -lMrm -lXm -lXt -lddif \
-lXext -lX11 -lm -li
 

Description

The Programmer’s Hierarchical Interactive Graphics System (PHIGS) is a language- and machine-independent standard for three-dimensional graphics that produces computer-generated pictures on vector or raster output devices.  It is a high-level interface that can be learned quickly and makes graphics programming easy. 

With Digital PHIGS, you can access functions by one of three sets of subroutine calls.  Digital PHIGS provides language interfaces in Fortran and C, as well as an OpenVMS interface that enables Digital PHIGS functions to be called from different languages. 

The Fortran and C interfaces enable users to transport PHIGS applications written in those languages to other operating systems that are running conforming implementations of PHIGS and the Fortran or C binding.  A conforming application is one that is consistent with the ISO and ANSI PHIGS standards. 

For more information about PHIGS and the Digital implementation of PHIGS, see the language binding manuals. 

The specific method for using Digital PHIGS software depends on the features and conventions of each language. This section describes general issues that must be considered when using the ULTRIX and DEC C compilers (cc). 

Supported Devices

In many applications, you may wish to write completely device-independent programs.  In this way, you can run your programs using different devices without having to rewrite your programs. On Digital UNIX systems, Digital PHIGS supports Motif, Motif-PEX, DDIF, PostScript, and CGM devices.  On ULTRIX systems, Digital PHIGS also supports ReGIS, Tektronix, HP--GL, sixel, color sixel, and DECwindows Toolkit devices. 

You may wish to review the range of capabilities of the Digital PHIGS supported devices, or you may wish to write device-dependent subroutines within your application.  In any instance, it is helpful to review the device-specific chapters in the "Device Specifics Reference Manual for DEC GKS and DEC PHIGS"  before you begin coding your application. The device-specific chapters contain information concerning predefined bundle index representations, color capabilities, initial input values, bit masks as workstation type values, supported escape functions for that particular device, and other information. 

Definition Files

Digital PHIGS constants and their values must be made available to all programs using Digital PHIGS regardless of the language you use. All high-level languages that use Digital PHIGS have a method for inserting an external file into the program source code stream at compile time. Incorporating an external file is the method for making Digital PHIGS constants available. 

Your installation kit has been supplied with files that contain Digital PHIGS constants and separate files that contain Digital PHIGS completion status code constants. You incorporate these files into your program with a statement that is appropriate to the language you are using. 

C Binding

The C programming language provides the #include statement for inserting an external file into a program. Therefore, any C program that uses the C binding should contain the following statement:

#include <PHIGS/phigs.h>

The language definition file for the C binding is phigs.h and is located in /usr/include/PHIGS. 

The completion status code definition file is phigs_msgs.h and is located in /usr/include/PHIGS. 

Each file includes comments that describe the exact method for using the definition file. 

Additional constants and data types are defined in the file phigs_defs.h, located in /usr/include/PHIGS. 

Fortran Binding

Any Fortran program that uses the Fortran binding functions should contain the following statement:

include ’/usr/include/PHIGS/phigs_for_bnd_consts.f’

The language definition file for the Fortran binding is located in the directory /usr/include/PHIGS and is named phigs_for_bnd_consts.f. 

The completion status code definition file for Fortran is located in the directory /usr/include/PHIGS and is named phigs_msgs.f. 

Each file includes comments that describe the exact method for using a given definition file. 

Workstation types are defined in the file phigs_defs.f. 

Ada Binding

Ada provides the "with" statement for referencing external information in the program.  The Ada language definition constants are defined in the PHIGS package, and all data type definitions are in the PHIGS_TYPES package.  Therefore, an Ada program that uses the Digital PHIGS Ada binding should contain the following lines:

with PHIGS;
with PHIGS_TYPES;
 use PHIGS;
use PHIGS_TYPES;

In addition to the PHIGS and PHIGS_TYPES packages, Digital PHIGS includes the following packages:

- PHIGS_CONFIGURATION
Sets implementation-dependent limit values for
various types defined in the binding.
- PHIGS_LIST_UTILITIES
Provides type declarations and operations for
list types that correspond to PHIGS list types.
- PHIGS_NAME_SET_FACILITY
Defines private types for name sets and provides
functions for building and manipulating name sets.
- PHIGS_ESCAPE
Provides support for registered escape functions.

Compiling, Linking, and Running Your Programs

A program that uses Digital PHIGS function calls should be compiled and executed as any other program. Use the compile command that is appropriate to the language you are using. To run an executable program, type the executable file name that you specified. 
 

Linking with the ISO C Binding Shareable Library

(Digital UNIX Only)

To link programs against the ISO C language binding shareable library, use the following syntax:

# cc -o application application.o -lPHIGSISO_C
 

Linking with the ISO C Binding Archive File

(Digital UNIX Only)

To link programs against the ISO C language binding archive file, use the following syntax:

 # cc -o application application.o /usr/lib/libPHIGSISO_C.a -lDXm\
  -lMrm -lXm -lXt -lpcm -ldecpex -lX11 -lXext -lcda -lbsd -lm -llmf

 

Linking with the Digital C Binding Shareable Library

(Digital UNIX Only)

To link programs against the Digital C language binding shareable library, use the following syntax:

# cc -o application application.o -lPHIGSC
 

Linking with the Digital C Binding Archive File

To link programs against the Digital C language binding archive file, use the following syntax:

Digital UNIX
 # cc -o application application.o /usr/lib/libPHIGSC.a -lDXm\
  -lMrm -lXm -lXt -lpcm -ldecpex -lX11 -lXext -lcda -lbsd -lm -llmf
  ULTRIX
 # cc -o application application.o /usr/lib/libPHIGSC.a \
  -lMrm -lXm -lXt -lddif -lXext -lX11 -lm -li
 

Linking with the PHIGS$ Binding Shareable Library

(Digital UNIX Only)

To link programs against the PHIGS$ language binding shareable library, use the following syntax:

# cc -o application application.o -lPHIGS
 

Linking with the PHIGS$ Binding Archive File

To link programs against the PHIGS$ language binding archive file, use the following syntax:

Digital UNIX
 # cc -o application application.o /usr/lib/libPHIGS.a  -lDXm\
  -lMrm -lXm -lXt -lpcm -ldecpex -lX11 -lXext -lcda -lbsd -lm -llmf
  ULTRIX
 # cc -o application application.o /usr/lib/libPHIGSC.a \
  -lMrm -lXm -lXt -lddif -lXext -lX11 -lm -li
 

Linking with the Fortran Binding

To link programs against the Fortran language binding archive file, use the following syntax:

Digital UNIX
 # f77 -o application -fpe1 application.o -lPHIGSDFOBND -lPHIGS
  ULTRIX
 # f77 -o application -fpe1 application.o -lPHIGSDFRBND -lPHIGS \
  -lMrm -lXm -lXt -lXext -lddif -lc -lX11 -lm -lc -li
 

Linking with the Ada Binding

To link programs against the ada language binding archive file, perform the following actions:

Digital UNIX
 1.  Create a Digital Ada program library with the Digital PHIGS Ada binding
    program library context as its default context:
 # amklib -p@/usr/lib/PHIGSadalib adalib
 2.  Compile the application test1.ada:
 # ada -A@adalib test1.ada
 3.  Link the application:
 # ald -A@adalib -o test1 test1 -lPHIGSADA -lPHIGS -lDXm\
-lMrm -lXm -lXt -lpcm -ldecpex -lX11 -lXext \
-lcda -lbsd -lm -llmf
  ULTRIX
 The Ada binding is not available on ULTRIX at this time.
 

Environment Variables

Environment variables are variables defined and maintained by the system.  This section describes the use of environment variables in your Digital PHIGS application. 

C Programs

In many Digital PHIGS C programs, your application appears as follows:

     popenphigs( stderr, 0);
     popenws( 1, PPCONID_DEFAULT, PPWSTYPE_DEFAULT );
        .
        .
        .
/∗   Release the Digital PHIGS and workstation environments.   ∗/
     pclosews( 1 );
     pclosephigs();

In this call to OPEN PHIGS, the name stderr is one of the arguments to the function.  This argument tells Digital PHIGS where to write generated error messages. 

If you pass the name stderr (or the value 0), Digital PHIGS writes the error messages to the specified location.  By default, stderr goes to the device /dev/tty, which translates to the default device connection of your process (error messages appear on your terminal’s display surface). 

If you choose, you can specify a path name as the first argument to OPEN PHIGS.  In this way, you have a permanent record of generated error messages for use during program debugging. 

The constant PPCONID_DEFAULT (or the value 0) tells Digital PHIGS to evaluate the environment variable PHIGSconid to determine the device connection. 

The constant PPWSTYPE_DEFAULT (or the value 0) tells Digital PHIGS to evaluate the environment variable PHIGSwstype to determine the workstation type. 

Fortran Programs

In many Fortran Digital PHIGS programs, your application appears as follows:

     CALL POPPH( 6, 0 )
     CALL POPWK( 1, DDCNID, DDWSTP )
        .
        .
        .
C    Release the Digital PHIGS and workstation environments.
     CALL PCLWK( 1 )
     CALL PCLPH()

In this call to OPEN PHIGS, the value 6 is one of the two arguments to the function.  This argument tells Digital PHIGS where to write generated error messages.  ’6’ refers to stdout, which means Digital PHIGS will write all errors to stdout. 

If you choose, you can specify a path name as the first argument to OPEN PHIGS.  In this way, you have a permanent record of generated error messages for use during program debugging. 

The constant DDCNID (or the value 0) tells Digital PHIGS to evaluate the environment variable PHIGSconid to determine the device connection. 

The constant DDWSTP (or the value 0) tells Digital PHIGS to evaluate the environment variable PHIGSwstype to determine the workstation type. 

The setenv Command

You can use the setenv command to your shell to define the environment variables to be the connection and type with which you are working, as follows:

csh> setenv  PHIGSconid  :0
csh> setenv  PHIGSwstype  231
csh> application
   .
   .
   .
csh> setenv  PHIGSconid  phigs_output.ps
csh> setenv  PHIGSwstype  61
csh> application
   .
   .
   .

The ability to define PHIGSconid and PHIGSwstype provides device independence. 

Digital PHIGS Environment Variables

The following table lists critical Digital UNIX and ULTRIX environment variables supported by Digital PHIGS.  For a complete list, see the "Device Specifics Reference Manual for DEC GKS and DEC PHIGS". 

Environment Variable	Description
PHIGSwstype	Specifies the default workstation type.
PHIGSconid	Specifies the default workstation connection information.
PHIGSdouble_buffering	Specifies that double buffering should be enabled.  Defaults to FALSE (0) for PEX and Motif workstations.
PHIGSanti_aliasing	Specifies that anti-aliasing should be enabled.  Defaults to FALSE (0) for PEX workstations.  Has no effect on workstations that do not support anti-aliasing.
PHIGSdevice_struct_support_24∗	Specifies the structure mode for PEX workstations.  Only client-side structures (value 0) and server-side structures (value 3) are supported. Defaults to server-side structures.
PHIGSClear_IZ	Specifies that the server should automatically clear the image and Z-buffer when starting a structure traversal.  Defaults to TRUE (1) for PEX workstations.
PHIGSnum_red_for_true	Specifies the number of shades of red Digital PHIGS should allocate in the true color map.  Defaults to eight shades of red.  Only used on PEX 8-plane workstations.
PHIGSnum_green_for_true	Specifies the number of shades of green Digital PHIGS should allocate in the true color map.  Defaults to four shades of green.  Only used on PEX 8-plane workstations.
PHIGSnum_blue_for_true	Specifies the number of shades of blue Digital PHIGS should allocate in the true color map.  Defaults to four shades of blue.  Only used on PEX 8-plane workstations.
PHIGSnum_pseudo_colors	Specifies the number of color cells that Digital PHIGS should use for its pseudocolor table.  Defaults to 64 color cells.
PHIGSuse_default_color_map	Specifies which color map Digital PHIGS uses.  If set to 0, Digital PHIGS uses a private color map.  If set to 1, Digital PHIGS uses the default color map.  The default is 0.  Only used on PEX 8-plane workstations (workstation type 241).
PHIGSmit_db_enable	Specifies which type of double buffering Digital PHIGS uses.  If set to 0, PHIGSmit_db_enable disables MIT double buffering and enables pixmap double buffering.  The default is 1.  Only used on PEX workstations.
PHIGSinput_fixed	Specifies whether a choice-, string-, or valuator-class input device is fixed to the main output widget or nonfixed to any widget.  A value of 0 nonfixes the widget; 1 fixes the widget.  For Motif, the default value is 0.
PHIGSresize_zoom	Specifies how the output image behaves when the main application widget is resized.  A value of 0 sets scrolling resize mode of the output image.  A value of 1 sets zoom resize mode of the output image.  For Motif, the default value is 1.

Bit Masks

You have the option of specifying the workstation type value in either a hexadecimal, octal, or decimal longword value.  In most cases, it is sufficient to specify the type value in decimal. 

However, some of the Digital PHIGS supported devices allow you to pass a bit mask in the first word of the longword workstation type value.  For example, the following definition establishes the Digital PHIGS workstation type as a Motif input/output workstation:

csh> setenv  PHIGSwstype   231

The following hexadecimal workstation type specifies to Digital PHIGS to allocate 128 colors in the color table for a Motif input/output workstation. 

csh> setenv  PHIGSwstype  %x008000E7

For a complete list of all of the available bit masks for a given device, refer to the appropriate chapter in the "Device Specifics Reference Manual for DEC GKS and DEC PHIGS".