NAME

intro_phigs − introduction to the SunPHIGS graphics library

DESCRIPTION

The functions in the SunPHIGS graphics library implement the Programmer’s Hierarchical Interactive Graphics System or PHIGS.  These reference manual pages describe the syntax of each function in the SunPHIGS graphics library.  Their organization is similar to the SunOS Reference Manual.  The first section is divided into manual entries for each function.  These manual entries are further divided into sections that describe C syntax, FORTRAN syntax, function parameters, and error messages. 

Reserved Names

SunPHIGS applications should avoid using variable and function names that conflict with names that SunPHIGS uses internally.  Since SunPHIGS programs are linked to the SunView, SunWindow, and Pixrect libraries, do not use symbols that start with the prefixes reserved by those packages, nor any symbol in the Math library nor any system call.  The public symbol names provided by SunPHIGS all start with p.  To avoid conflicts with the SunPHIGS name space, do not define any of the following symbols:

•  PHIGS C and FORTRAN function names
•  Names with the prefixes phigs, phg, or pxx.  (The x is literal. It does not stand for anything.) 
•  System library symbols, such as time. 

Abbreviations

The following list describes the abbreviations used in the reference manual. 

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

Most PHIGS functions are allowed only in certain states.  The SYNOPSIS section of each function encodes the Required PHIGS Operating States.  An asterisk (∗) is used when an operating state variable may be in either state (that is, does not matter).  All of the operating states are initially closed. 

Deviations from the PHIGS Standard

1.Sun’s grayscale systems are monochrome by the PHIGS definition, but INQUIRE WORKSTATION TYPE will return colour. 

2.Currently, SunPHIGS only supports the RGB colour model.  The coordinate space is [0,1] in all three dimensions. 

Limitations

The following limitations are permitted by the PHIGS standard. 

1.The PATTERN fill style is not supported. 

2.CELL ARRAY uses the minimal simulation by drawing the bounding quadrilateral. 

3.No metafile input workstations are supported. 

Extensions to the PHIGS Standard

The SunPHIGS library contains the following optional functions that are not in the PHIGS specification, but are extremely useful in the Sun environment. 

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

The SunPHIGS Extensions Reference Manual describes additional extension functions, including some from PHIGS+. 

Include Files

In order to lessen the likelihood of passing bad data and ease any future changes in functionality, SunPHIGS applications should use the constants and enumerated values defined in the proper header files.  C applications should include the file phigs.h.  Every FORTRAN programming unit should include the file phigs77.h to gain access to the default workstation types and SunPHIGS FORTRAN constants.  See the example programs in and below /usr/lib/phigs1.1/examples or in Getting Started with SunPHIGS. 

Common Problems

1.You cannot mix Sun Tool and Sun Canvas workstations.  You must decide which workstation type to use at link-time and link appropriately. 

2.Sun Canvas workstations do not support logical input devices in REQUEST mode.  REQUEST operations will return a BREAK without waiting for operator input. 

3.SunPHIGS offers significant performance enhancements transparently when a graphics accelerator is available.  Features are provided in software when hardware support is unavailable.  ESCAPE -16 (3P) may be used to determine the level of hardware support.  The Device Dependent Acceleration chapter of the SunPHIGS1.1 Programmer’s Guide documents the supported accelerators and the SunPHIGS features they support.  This document also contains an appendix SunOS and Display Devices which describes the steps necessary for an accelerator to be available to SunPHIGS.  The example program WHAT_HW, from the examples directory, describes how to determine the system configuration and level of support for the various SunPHIGS features. 

4.The display update state heavily influences performance and visual results.  The default deferral mode is ASAP (As Soon As Possible), so most every structure edit or change to a workstation table entry causes a regeneration (that is, full structure traversal).  See SET DISPLAY UPDATE STATE (3P). 

5.Attempting to insert elements into an open structure while the edit mode is REPLACE is complicated.  In such a case, each inserted element will overwrite the existing element at the current element position.  In REPLACE mode, the element pointer is not implicitly incremented prior to inserting an element, as it is in INSERT mode. 

6.The C binding enumerated type values PREPLACE (a composition type for psetlocaltran) and PEDIT_REPLACE (an edit mode for pseteditmode) are dangerously similar. 

7.Some workstation description table inquiries require that the passed workstation type be a specific workstation type; that is, associated with an open workstation.  In these cases, if the workstation type passed to the inquiry function is not a specific type, error 051 will be returned, indicating that a specific workstation type must be used. 

8.Segmentation faults are often the result of passing bad pointers to the SunPHIGS C binding. 

9.The PHIGS standard says that the application should avoid recursive structure networks and that the implementation does not need to check for this problem.  SunPHIGS does not check for recursive structure networks.  One of the following error messages can occur when an application attempts to create a recursive structure network:

     SunPHIGS: child died on signal 11
     Segmentation fault (core dumped)

10.If the internal memory allocation within a system call fails for a reason such as a lack of swap space, a cryptic error message like the following example can result:

     gp1_makefromfd error: valloc failed
     pr_open: pixrect create failed for /dev/fb
This kind of message indicates that a lower level routine failed, telling SunPHIGS the status of the routine, but not why it failed.  This causes the SunPHIGS routine to fail, set the error state, and then continue.  Super-user can eliminate these errors by configuring the target system on which the application is run with a larger swap partition, or by removing processes to free up swap space. 

11.Very complex output primitives can take so long to process that the window system breaks the process window lock, resulting in messages such as:

     Window display lock broken after time limit exceeded by pid XXXX
     You may see display garbage because of this action
The default window lock limit is two seconds of process virtual time. (See pw_lock in the SunView Programmer’s Guide.) The amount of work that can be done during this time is system dependent, but generally adequate. Problems are more likely on a slower system without a graphics accelerator. (A solid or hatched fill area with about 1000 vertices might exceed two seconds on a Sun-4/260, regardless of the accelerator.) SunPHIGS continues traversal if no other window is attempting to lock the screen. The display may be correct, despite these messages. 

Super-user (of the target system) can eliminate these messages by increasing the kernel window lock time limit, ws_lock_limit; this is the maximum duration that a single process is allowed to monopolize the display.  For example, to set the kernel window lock time limit to 15 (0F hexadecimal) seconds, the commands and output would look like this:
     # echo ′ws_lock_limit?W 0F′  | adb -w /vmunix
     _ws_lock_limit: 0x2            =       0xf
The new value in /vmunix will take effect when the system next reboots.

To assure that the modification is retained when future kernels are rebuilt, update the kernel object file winlock.o.  (This file is in /sys/‘arch‘/OBJ on a system running SunOS 4.x, and in /sys/OBJ on any system running SunOS 3.5.)  For example, to set the kernel window lock time limit to 15 (0F hexadecimal) seconds on a Sun-3 system running 4.0, the commands and output would look like this:
     # cp /sys/sun3/OBJ/winlock.o /sys/sun3/OBJ/winlock.o-
     # echo ′ws_lock_limit?W 0F′  | adb -w /sys/sun3/OBJ/winlock.o
     _ws_lock_limit: 0x2             =       0xf

You can display the kernel window lock time limit (in hexadecimal seconds) using:
     # echo ′ws_lock_limit?X′ | adb /vmunix -

FORTRAN Binding Notes

SunPHIGS implements the PHIGS/FORTRAN ANS binding draft of October, 1987, known as X3.144.1-198x. 

There are two PHIGS FORTRAN bindings, one for full FORTRAN 77 and one for compilers that do not fully conform to the FORTRAN 77 specification.  In most cases these bindings are identical.  However, the bindings for some subroutines vary slightly.  For these functions, SunPHIGS provides both binding forms. 

The SunPHIGS FORTRAN binding corrects three parameter errors in the binding draft.  In INQUIRE DEFAULT STRING DEVICE DATA 3 and INQUIRE DEFAULT STRING DEVICE DATA, SunPHIGS includes the input argument INIPOS, the initial cursor position.  In INQUIRE TEXT EXTENT (both full and subset), SunPHIGS includes the input argument FONT, and returns the text extent rectangle using only two elements in x and y coordinate output arrays, named TXEXRX and TXEXRY.  For the functions INQUIRE ELEMENT CONTENT and INQUIRE CURRENT ELEMENT CONTENT, SunPHIGS also corrects the FORTRAN binding data record definitions for FILL AREA SET 3 and FILL AREA SET elements. 

If an array size specified by the application is too small to hold all of the data that should be returned, an error is raised.  In this case, output parameters indicating the number of array elements being returned are not set to zero, which would reflect that no array elements are in fact being returned.  Instead, the SunPHIGS FORTRAN binding returns the actual array size in this case, to tell application how much space is needed to obtain the requested data.  (INQUIRE CURRENT ELEMENT CONTENT is an exception to this because the required data is already available from INQUIRE CURRENT ELEMENT TYPE AND SIZE.) 

Intermixing calls to the SunPHIGS C and FORTRAN language bindings is not supported.  At the application level, languages may be mixed, but SunPHIGS functions may be called in only one language binding per application. 

C Binding Notes

Sun has updated the ISO C binding draft of 6 July 1987 to match the PHIGS International Standard (ISO 9592, and ANSI document X3H3/89-54), and in doing so minimal changes have been made. The C binding (ISO ID 9593-4) is still in a draft form separate from the PHIGS standard.  The final C binding is expected to be different from the current draft. 

The ISO C binding draft has the following error: PESTOP should be specified PENOTSTOP according to the rules for deriving enumerated type names for the C binding. The SunPHIGS include file phigs.h contains this correction. 

Certain C binding functions are defined in the binding (Section 3.9.3) that return complex data types.  For these, the application allocates a block of memory and the binding function stores the data which is into the block of memory the user provides.  For these functions, the buffer must either be aligned correctly for the data to be returned, or maximally aligned. This is especially critical for applications that may run on Sun-4 systems, since the Sun-4 has more critical alignment requirements than the Sun-3.  Maximal alignment is provided automatically by the system memory allocation functions (see malloc(3)).  If malloc is not used, the alignment is the responsibility of the application.  We suggest an array of double-s since they have the maximal alignment restriction and any C data type may be stored there. 

SEE ALSO

COLOUR(7)
PHIGS DESCRIPTION TABLE(7)
PHIGS TRAVERSAL STATE LIST(7)
PHIGS WORKSTATION DESCRIPTION TABLE(7)
CGM(7)
INTRO PHIGS+ (3P+)

Sun Release 4.0  —  Last change: 31 July 1989