NAME

intro_phigs − introduction to the PEX-SI graphics library

DESCRIPTION

The PEX-SI graphics library implements the Programmer’s Hierarchical Interactive Graphics System (PHIGS) and portions of the proposed PHIGS extension (PHIGS PLUS).  This PHIGS implementation is designed specifically and exclusively for use with X servers that implement the PEX extension. 

These manual pages describe the syntax of each function in the PEX-SI graphics library. There is one entry for each function. 

Reserved Names

PEX-SI applications should avoid using variable and function names that conflict with names that PEX-SI uses internally.  Since PEX-SI programs are linked to the Xlib library, do not use symbols that start with the prefixes reserved by that package, symbols in the Math library, or system calls.  The public symbol names provided by PEX-SI all start with p.  To avoid conflicts with the PEX-SI name space, do not define any of the following symbols:

•  PHIGS or PHIGS PLUS C function names
•  Names with the prefixes phigs, phg,  P, or p. 
•  System library symbols, such as time. 

Abbreviations

The following list describes the abbreviations used in this manual. 

PHIGS has four operating state variables, each with two possible values:

Each PHIGS function requires that PHIGS be in a certain operating state before the function can be called.  The SYNOPSIS section of each function specifies the required value that each of the four operating state variables must have to call that function.  An asterisk (∗) is used when an operating state variable may be in either state (that is, does not matter).  All of the operating state variables are initially set to the closed value. 

Extensions to the PHIGS Standard

The PEX-SI library contains the following optional functions that are not in the PHIGS specification, but are extremely useful. 

WORKSTATION TYPE CREATE
WORKSTATION TYPE DESTROY
WORKSTATION TYPE GET
WORKSTATION TYPE SET

Include Files

PEX-SI applications should use the constants and enumerated values defined in the PHIGS files to decrease the possibility of passing bad data and avoid conflict with future changes.  C applications should include the file phigs.h.  See the example programs in Xsrc/extensions/clients/PEX/demo. 

C Binding Notes

The C binding used for the PEX-SI graphics library matches the PHIGS C Binding (Draft ISO DIS 9593-4:199x(E), 1 August 1990), for the PHIGS standard functions, with several deviations.  These deviations either correct bugs in the DIS binding or anticipate changes that will be made when the DIS is approved.  The following lists the PEX SI deviations from the DIS binding. 

1.In the definition of the data type Pcolr_rep, the name of the Phsv field is hsv, not hlv. 

2.All Pdouble usage in the DIS binding is Pfloat in the PEX-SI binding. 

3.Everywhere the DIS binding lists the parameter “Pstore ∗store”, PEX-SI uses “Pstore store”.  In other words, the store object is passed directly, and not as a pointer the store object. 

4.The Pstring_data and Pstring_data3 structures in PEX-SI are different from those specified in the DIS binding.  Pstring_data and Pstring_data3 are defined as follows in PEX-SI:

typedef struct {
Pintbuffer_size;/∗ input buffer size ∗/
Pintinit_pos;/∗ initial editing position ∗/
union {
Pintunused;
} pet_r1;
} Pstring_data;
typedefPstring_dataPstring_data3;

5.The following functions do not have the in_buf_size and init_pos parameters listed in the DIS binding.  Those fields are instead in the Pstring_data (or Pstring_data3) structure passed to these functions:

INITIALIZE STRING
INITIALIZE STRING 3
INQUIRE STRING DEVICE STATE
INQUIRE STRING DEVICE STATE 3
INQUIRE DEFAULT STRING DEVICE STATE
INQUIRE DEFAULT STRING DEVICE STATE 3

6.The Pstroke_data and Pstroke_data3 structures in PEX-SI are different from those specified in the DIS binding.  Pstroke_data and Pstroke_data3 are defined as follows in PEX-SI:

typedef struct {
Pintbuffer_size;/∗ input buffer size ∗/
Pintinit_pos;/∗ initial editing position ∗/
Pfloatx_interval;/∗ x interval ∗/
Pfloaty_interval;/∗ y interval ∗/
Pfloattime_interval;/∗ time interval ∗/
union {
struct {
Pintunused;
} pet_r1;
struct {
Pintunused;
} pet_r2;
struct {
Pmarker_attrsmarker_attrs; /∗ marker attributes ∗/
} pet_r3;
struct {
Pline_attrsline_attrs;/∗ line attributes ∗/
} pet_r4;
} pets;
} Pstroke_data;
/∗ Pstroke_data3 -- stroke data record 3 ∗/
typedef struct {
Pintbuffer_size;/∗ input buffer size ∗/
Pintinit_pos;/∗ initial editing position ∗/
Pfloatx_interval;/∗ x interval ∗/
Pfloaty_interval;/∗ y interval ∗/
Pfloatz_interval;/∗ z interval ∗/
Pfloattime_interval;/∗ time interval ∗/
union {
struct {
Pint      unused;
} pet_r1;
struct {
Pint      unused;
} pet_r2;
struct {
Pmarker_attrsmarker_attrs; /∗ marker attributes ∗/
} pet_r3;
struct {
Pline_attrsline_attrs;/∗ line attributes ∗/
} pet_r4;
} pets;
} Pstroke_data3;

7.The following functions do not have the in_buf_size and init_pos fields listed in the DIS binding.  Those fields are instead in the Pstroke_data or Pstroke_data3 structure passed to these functions:

INITIALIZE STROKE
INITIALIZE STROKE 3
INQUIRE STROKE DEVICE STATE
INQUIRE STROKE DEVICE STATE 3
INQUIRE DEFAULT STROKE DEVICE STATE
INQUIRE DEFAULT STROKE DEVICE STATE 3

8.The Pval_data and Pval_data3 structures in PEX-SI are different from those specified in the DIS binding.  Pval_data and Pval_data3 are defined as follows in PEX-SI:

typedef struct {
Pfloatlow;/∗ low range limit ∗/
Pfloathigh;/∗ high range limit ∗/
union {
struct {
Pintunused;
} pet_r1;
struct {
Pchar∗label;
Pchar∗format;
Pchar∗low_label;
Pchar∗high_label;
} pet_u1;
} pets;
} Pval_data;
typedefPval_dataPval_data3;

9.The following functions do not have the low_value and high_value parameters  listed in the DIS binding.  Those fields are instead in the Pval_data (or Pval_data3) structure passed to these functions. 

INITIALIZE VALUATOR
INITIALIZE VALUATOR 3
INQUIRE VALUATOR DEVICE STATE
INQUIRE VALUATOR DEVICE STATE 3
INQUIRE DEFAULT VALUATOR DEVICE STATE
INQUIRE DEFAULT VALUATOR DEVICE STATE 3

10.The PEX-SI binding uses “char ∗” instead of “void ∗”. 

11.Pedge_attrs.colr_asf is Pedge_attrs.colr_ind_asf in PEX-SI. 

12.Pline_attrs.colr_asf is Pline_attrs.colr_ind_asf in PEX-SI. 

13.Pint_attrs.colr_asf is Pint_attrs.colr_ind_asf in PEX-SI. 

14.Pmarker_attrs.colr_asf is Pmarker_attrs.colr_ind_asf in PEX-SI. 

15.In INQUIRE ANNOTATION FACILITIES the last parameter has been replaced with two Pfloat pointers:

pinq_anno_facs ( type, length, start, error_ind, styles, total_length, num_anno_char_hts,
          min_char_ht, max_char_ht )
Pwstypetype;workstation type
Pintlength;length of application list
Pintstart;starting position
Pint∗error_ind;OUT error indicator
Pint_list∗styles;OUT list annotation styles
Pint∗total_length;OUT length of list in PHIGS
Pint∗num_anno_char_hts; OUT number of character heights
Pfloat∗min_char_ht;OUT minimum character height
Pfloat∗max_char_ht;OUT maximum character height

16.The second parameter to the function pset_pat_ref_point_vec is "Pvec3  pat_ref_vec[2]", not "Pvec3  ∗pat_ref_vec[2]". 

17.The connection identifier argument to the function pinq_ws_conn_type is "Pconnid  ∗conn_id". 

18.The function identification numbers in the file phigscfunc.h do not all agree with the numbers specified in the DIS C binding.  the transformation utilities (numbers 90 through 109 in the DIS binding) do not have identification numbers in PEX-SI because those functions never invoke error handling.  See phigscfun.h for the function numbers that PEX-SI assigns. 

The macro names used in phigscfunc.h do correspond to those in the DIS binding, but the numbers associated with each macro may be different.  If your application uses the defined macros, the differences in the identification numbers should not cause any problems. 

A definition of the binding is in the file Xsrc/extensions/lib/PEX/c_binding/phigs.c_bind.  This file contains stubs for all of the binding functions and is used to build the lint library.  The data structures are defined in the file Xsrc/extensions/lib/PEX/include/phigs.h. 

Structure Storage

The API supports client side and server side CSS.  Client side CSS is used if the connecting server does not support structure storage. 

PHIGS Monitor (PM)

To meet many of the goals and constraints of PHIGS, PHIGS PLUS, X, and PEX, the PEX-SI graphics library is implemented as two processes. One process resides in the client’s process and one resides in a separate process called the PHIGS Monitor (PM). The PM processes window system and input device events associated with a client’s PHIGS workstations, implements the window system event queue, and services event requests and inquiries from the client-side API code. The PM also contains the CSS for PHIGS workstations that exist on the client side. 

There is one PHIGS monitor per PHIGS client, and it monitors all PHIGS workstations opened by that client regardless of what server each workstation is on.  The PM process always runs on the same machine as the client. 

SEE ALSO

COLOUR(7)
PHIGS DESCRIPTION TABLE(7)
PHIGS TRAVERSAL STATE LIST(7)
PHIGS WORKSTATION DESCRIPTION TABLE(7)

September 02, 1992