ISO/IEC 9593-4:1991

Information technology - Computer graphics - Programmer's Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C

Specifies a language independent nucleus of a graphics system. Specifies also a language dependent layer for the C language. Annexes A, B, C, D and E are for information only.

Technologies de l'information — Infographie — Interfaces langage avec PHIGS — Partie 4: C

General Information

• Status: Published
• Publication Date: 17-Dec-1991
• ICS: 35.060 - Languages used in information technology
• ICS: 35.140 - Computer graphics
• Technical Committee: ISO/IEC JTC 1/SC 24 - Computer graphics, image processing and environmental data representation
• Drafting Committee: ISO/IEC JTC 1/SC 24 - Computer graphics, image processing and environmental data representation
• Current Stage: 9093 - International Standard confirmed
• Start Date: 08-Dec-2021
• Completion Date: 30-Oct-2025

Relations

• Amended By: ISO/IEC 9593-4:1991/Amd 1:1994 - Information technology - Computer graphics - Programmer's Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C - Amendment 1
• Effective Date: 06-Jun-2022
• Amended By: ISO/IEC 9593-4:1991/Amd 2:1998 - Information technology - Computer graphics - Programmer's Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C - Amendment 2: Incorporation of PHIGS amendments
• Effective Date: 06-Jun-2022
• Parent: ISO/IEC 9593-4:1991/Amd 2:1998 - Information technology - Computer graphics - Programmer's Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C - Amendment 2: Incorporation of PHIGS amendments
• Effective Date: 15-Apr-2008
• Parent: ISO/IEC 9593-4:1991/Amd 1:1994 - Information technology - Computer graphics - Programmer's Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C - Amendment 1
• Effective Date: 15-Apr-2008

Overview

ISO/IEC 9593-4:1991 - "Information technology - Computer graphics - Programmer’s Hierarchical Interactive Graphics System (PHIGS) language bindings - Part 4: C" specifies a language‑independent nucleus of the PHIGS graphics system and defines the C language binding for that nucleus. The standard documents the C API for PHIGS implementations, including type and macro definitions, function bindings, memory management rules and error handling. Several annexes (A–E) provide informative material: data types, example programs, short‑identifier macros and memory‑management guidance.

Key topics and technical requirements

• Language-independent nucleus + C binding: Defines a portable PHIGS core and a C-specific layer to map PHIGS concepts into C.
• Function and macro conventions: Rules on when functions or macros are provided, naming and registration of identifiers.
• Type and header definitions: Mapping of PHIGS data types to C types, environmental and implementation‑dependent definitions, and required headers.
• Memory management: Detailed guidance for inquiry functions that return simple lists versus complex data structures; meaning of element sizes and allocation expectations.
• Error handling: Standardized error codes, C‑specific PHIGS errors and support for application‑defined error handlers.
• Storage formats: Conventions for storing two‑dimensional data such as matrices and colour arrays.
• API coverage: Comprehensive C function sets for control, output primitives, attribute specification (bundled and individual), transformations and clipping, structure content and manipulation, display and archiving, input device handling (sample/event/request), metafile I/O and inquiry operations.
• Tables and macros: Abbreviation policies, function name tables, macro definitions for function identifiers, error codes, plotting styles and default parameters.

Applications and practical value

• Implements a standard PHIGS C API for portable graphics applications and workstation drivers.
• Useful for CAD/CAM, scientific visualization, engineering graphics and legacy systems requiring hierarchical interactive graphics.
• Facilitates interoperability between different PHIGS implementations and consistent behaviour across platforms.
• Annex example programs and short‑identifier macros speed up prototyping and help vendors implement the binding correctly.

Who should use this standard

• Graphics library implementers and maintainers building or porting PHIGS in C.
• Application developers targeting PHIGS for structured interactive graphics.
• System integrators creating workstation or metafile tools that must comply with PHIGS conventions.
• Educators and researchers working with historical or standards‑compliant graphics APIs.

Related standards

• Part of the ISO/IEC 9593 series defining PHIGS language bindings; consult other parts of the series for language bindings and the general PHIGS specification.

Standards Content (Sample)

INTERNATIONAL
STANDARD
First edition
1991-12-15
~____-------------__---
-- ___^___ ___- -__-_ II____p
Information technology - Computer graphics -
Programmer’s Hierarchical Interactive Graphics
System (PHIGS) language bindings -
Part 4:
c
-. lnfographie
Technologies de I ‘informa tion - - Interfaces langage entre
un programm e d’applica ti on et son support graphique --
Partie 4: C
Reference number
ISOAEC 9593-4: 1991
(E)
ISO/IEC 9593-4: 1991(E)
Foreword
Contents
1 scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.................................................................................................................................................
2 Normative references
............................................................................................................................
3 The C language binding of PHIGS
......................................................................................................................................................
3.1 Conformance
....................................................................................................................................
3.2 Functions versus macros
3.3 Character strings .
3.4 Function identifiers .
3.5 Registration .
..............................................................................................................................
3.6 Identifiers for graphics items
......................................................................................................................................................
3.7 Return values
........................................................................................................................................................
3.8 Header files
........................................................................................................................................
3.9 Memory management
..........................................................................................
3.9.1 Inquiry functions which return simple lists
......................................................................
3.9.2 Inquiry functions which return complex data structures
.......................................................................................................
3.9.3 Meaning of the size of an element
3.10 Inquiries returning structure elements .
3.11 Error handling .
Application defined error handlers .
3.11.1
3.11.2 Error codes .
3.11.3 C specific PHIGS errors .
........................................................................................................................
3.12 Storage of two-dimensional data
...............................................................................................................................
3.12.1 Storage of matrices
.......................................................................................................................
3.12.2 Storage of colour arrays
4 Tables .
..........................................................................................
4.1 Abbreviation policy for construction of identifiers
4.2 Table of abbreviations .
4.3 Function names .
.......................................................................................
4.3.1 List ordered alphabetically by bound name
.......................................................................
4.3.2 List ordered alphabetically by PHIGS function name
5 Type definitions .
5.1 Mapping of PHIGS data types .
........................................................................................................................
5.2 Environmental type definitions
.....................................................................................................
5.3 Implementation dependent type definitions
..................................................................................................
5.4 Implementation independent type definitions
6 Macro definitions .
6.1 Function identifiers .
6.2 Error codes .
6.3 Miscellaneous .
6.3.1 Linetypes .
6.3.2 Marker types .
6.3.3 Annotation styles .
6.3.4 Colour models .
6.3.5 Prompt and Echo Types .
.................................................................................................
6.3.6 Default parameters of OPEN PHIGS
6.3.7 Element enumeration .
0 ISO/IEC 1991
All rights reserved. No part of this publication may be reproduced or utilized in any form or by
any means, electronic or mechanical, including photocopying and microfilm, without permission
in writing from the publisher.
ISO/IEC Copyright Office a Case postale 56 l CH-1211 Geneve 20 l Switzerland
Printed in Switzerland
ii
ISO/IEC 9593-4: 1991(E)
Foreword
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7 C PHIGS functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1 Notational conventions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
7.2 Control functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Output primitive functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.
7.4 Attribute specification functions
7.4.1 Bundled attribute selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.
7.4.2 Individual attribute selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.3 Aspect source flag setting
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.4 Workstation attribute table definition
Workstation filter definition . .*.
7.4.5
Colour model control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.7 HLHSR attributes
............................................................................................................
7.5 Transformation and clipping functions
7.5.1 Modelling transformations and clipping .
...................................................................................................................................
7.5.2 View operation
...............................................................................................................
7.5.3 Workstation transformation
.............................................................................................
7.5.4 Utility functions to support modelling
................................................................................................
7.5.5 Utility functions to support viewing
............................................................................................................................
7.6 Structure content functions
7.7 Structure manipulation functions .
7.8 Structure display functions .
7.9 Structure archiving functions .
7.10 Input functions .
....................................................................................................................
7.10.1 Pick identifier and filter
...........................................................................................................
7.10.2 Initialization of input devices
....................................................................................................
7.10.3 Setting the mode of input devices
....................................................................................................................
7.10.4 Request input functions
7.10.5 Sample input functions .
7.10.6 Event input functions .
7.11 Metafile functions .
7.12 Inquiry functions .
.....................................................................................
7.12.1 Inquiry functions for operating state values
7.12.2 Inquiry functions for PHIGS description table .
..............................................................................................
7.12.3 Inquiry functions for PHIGS state list
Inquiry functions for workstation state list .
7.12.4
.........................................................................
7.12.5 Inquiry functions for workstation description table
.............................................................................................
7.12.6 Inquiry function for structure state list
............................................................................................
7.12.7 Inquiry functions for structure content
7.12.8 Inquiry functions for error state list .
7.13 Error control .
...........................................................................................................................................
7.14 Special interfaces
....................................................................................................................
7.15 Binding defined utility functions
Annexes
........................................................................................
A Data types in compilation order and external functions
A. 1 Macro definitions .
A.2 Types in compilation order .
A.3 External functions .
B Example Programs .
B.l star .
B.2 iron . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.
B.3 dyna star . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
show- line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B .4
B.5 xfor& pline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Macros forshort function identifiers
. . .
ill
ISO/IEC 9593-4: 1991(E)
Foreword
C. 1 Short function identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.
D Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
D. 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.2 Functions that return simple lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~. 285
D.2.1 Operationof ping list line inds
D.3 Functions that return complex data &uctur& . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
D.3.1 Operationof pcreate store
rep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.~. 291
D.3.2 Operationof pin -
D.3.3 Operation of pdel store . - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.*.*
-
E Function Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
E.l List of functions ordered alphabetically by function name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.2 List of functions ordered alphabetically by bound name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
ISO/IEC 9593=4:1991(E)
Foreword
IS0 (the International Organization for Standardization) and IEC (the International Electrotechnical Commission)
form the specialized system for worldwide standardization. National bodies that are members of IS0 or IEC
participate in the development of International Standards through technical committees established by the
respective organization to deal with particular fields of technical activity. IS0 and IEC technical committees
collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in
liaison with IS0 and IEC, also take part in the work.
In the field of information technology, IS0 and IEC have established a joint technical committee, ISO/IEC JTC 1.
Draft International Standards adopted by the joint technical committee are circulated to national bodies for voting.
Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote.
International Standard ISO/IEC 9593-4 was prepared by Joint Technical Committee ISOIIEC JTC 1, Information
technology.
ISO/IEC 9593 consists of the following parts, under the general title Information technology - Computer
graphics - Programmer’s Hierarchical Interactive Graphics System (PHIGS) language bindings :
-Part 1: FORTRAN 77
-Part 3 : ADA
-Part4: C
Annexes A, B, C, D, and E of this part of ISO/IEC 9593 are for information only.
V
ISO/IEC 9593=4:1991(E)
Introduction
The Programmer’s Hierarchical Interactive Graphics System (PHIGS), the functional description of which is given
in ISO/IEC 9592-1, is specified in a language independent manner and needs to be embedded in language dependent
layers (language bindings) for use with particular programming languages.
The purpose of this part of ISO/IEC 9593 is to define a standard binding for the C computer programming language.

INTERNATIONAL STANDARD ISO/IEC 9593=4:1991(E)
Information technology - Computer graphics -
Programmer’s Hierarchical Interactive Graphics System
(PHIGS) language bindings,-
Part 4:
C
1 Scope
The Programmer’s Hierarchical Interactive Graphics System (PHIGS), ISO/IEC 9592-1, specifies a language
independent nucleus of a graphics system. For integration into a programming language, PHIGS is embedded in a
language dependent layer obeying the particular conventions of that language. This part of ISO/IEC 9593 specifies
such a language dependent layer for the C language.
ISOIIEC 9593-4: 1991(E)
Normative references
2 Normative references
The following standards contain provisions which, through reference in this text, constitute provisions of this part of
ISO/IEC 9593. At the time of publication, the editions indicated were valid. All standards are subject to revision,
and parties to agreements based on this part of ISO/IEC 9593 are encouraged to investigate the possibility of apply-
ing the most recent editions of the standards indicated below. Members of IEC and IS0 maintain registers of
currently valid International Standards.
- Programmer’s Hierarchical Interactive
IS0 9592-l : 1989, Information processing systems - Computer graphics
Graphics System (PHIGS) - Part 1 :Functional description.
ISO/IEC 9899 : 1990, Programming Languages - C.
ISO/IEC TR 9973 : 1988, Information processing - Procedures for Registration of Graphical Items.

ISO/IEC 9593=4:1991(E)
The C language binding of PHIGS
3 The C language binding of PHIGS
3.1 Conformance
This binding incorporates the rules of conformance defined in the PHIGS Standard (ISO/IEC 9592) for PHIGS
implementations, with those additional requirements specifically defined for C language implementations of PHIGS.
The following criteria are established for determining conformance of an implementation to this binding:
In order to conform, an implementation of the C binding of PHIGS shall implement ISO/IEC 9592-l. It shall
make visible all of the declarations in the C binding specified in this part of ISO/IEC 9593.
Thus, for example, the syntax of the function names shall be precisely as specified in this part of ISO/IEC
9593 and the parameters shall be of the data types stated in this part of ISO/IEC 9593.
3.2 Functions versus macros
An implementation may substitute macros for functions. However, the macros must be designed so that side-effects
work properly.
3.3 Character strings
The C language represents character strings as an array of characters terminated by the null character (i.e. ‘W’).
This means that the null character is not usable as a printable character.
3.4 Function identifiers
The C standard (ISO/IEC 9899) requires that compilers recognize internal identifiers which are distinct in at least 31
characters. That standard also requires that external identifiers (i.e. those seen by the linker) be recognized to a
minimum of six characters, independent of case.
In order to produce more readable C code, this part of ISO/IEC 9593 binds the PHIGS function names to identifiers
which can be longer than six characters but are less than 31 characters. Implementations which must run in environ-
ments which honour less than 3 1 characters in external identifiers must include a set of #defines in the header
file which equate the long identifiers defined in this part of ISO/IEC 9593 to a set of shorter identifiers which con-
form to the requirements of the implementation. An example of these shorter names can be found in annex C.
3.5 Registration
ISO/IEC 9592-l reserves certain value ranges for registration1 as graphical items. The registered graphical items
will be bound to the C programming language (and other programming languages). The binding of registered items
will be consistent with the bindings presented in this part of ISO/IEC 9593.
3.6 Identifiers for graphics items
ISO/IEC 9592-l provides a mechanism to extend its functionality by the use of the graphical items GENERALIZED
DRAWING PRIMITIVE, GENERALIZED DRAWING PRIMITIVE 3, GENERALIZED STRUCTURE ELE-
MENT and ESCAPE. These items are referenced via identifiers formed from the registration number of the item.
This binding specifies the format of the identifiers but it does not specify the registration of the identifiers. The
identifiers are used as arguments to the functions pgdp, pgdp3, pgse, and pescape and returned to the appli-
cationbythefunctions pinq_elem content and pinq_cur elem content.
- - -
1 For the purpose of this International Standard and according to the rules for the designation and operation of registration authorities in the
ISO/IEC JTCl procedures, the IS0 and IEC Councils have designated the National Institute of Standards and Technology (National Computer
Systems Laboratory), A-266 Technology Building, Gaithersburg, MD 20899, USA, to act as registration authority.
ISO/IEC 95934 1991(E)
The C language binding of PHIGS
An implementation may also represent these items as separate functions, but this is not required.
The format of the identifiers for graphical items is
“PFFF Tn”
-
where:
FFF is the abbreviation of the PHIGS function name.
T is the type of the item, “R” for registered and “U” for unregistered.
n is the registration number (for unregistered items, the absolute value of the item number shall be used).
The formats for registered GENERALIZED DRAWING PRIMITIVE, GENERALIZED DRAWING PRIMITIVE
3, GENERALIZED STRUCTURE ELEMENT and ESCAPE graphical items are:
#define PGDP Rn n
( )
#define PGDP? Rn n
( 1
n
#define PGSE En ( 1
#define PESCiPE Rn
(n)
-
For example, the identifier for registered GENERALIZED DRAWING PRIMITIVE item 12 would be:
#define PGDP R12
(12)
-
The formats for unregistered GENERALIZED DRAWING PRIMITIVE, GENERALIZED DRAWING PRIMI-
TIVE 3, GENERALIZED STRUCTURE ELEMENT and ESCAPE graphical items are:
#define PGDP Un (-n)
#define PGDP? Un (4
#define PGSE in t-n)
#define PESCAPE Un (4
-
PRIMITIVE item -1 would be:
For example, the identifier for unregistered GENERALIZED DRAWING
#define PGDP Ul t-11
-
3.7 Return values
All PHIGS C functions return void.
3.8 Header files
C provides a mechanism to allow external files to be included in a compilation. The file phigs . h shall be
included in any application program that intends to use PHIGS via the C binding.
Clause 5 of this binding describes the data types that shall be defined in the file phigs . h; clause 6 defines the
macros that shall be in the file phigs . h. Additional implementation-dependent items may be placed in this file if
needed.
The type size t is used in the binding. It is defined in the standard header . Therefore, the file
phigs.h shall i&de Xstddef. h> inordertodefine size t.
-
The file phigs . h shall also contain external prototype declarations for all PHIGS C functions because they return
void. For example, the declaration for the function popenphigs is:
extern void popen_phigs(const char *err file, size t mem units);
- - -
ISO/IEC 9593=4:1991(E)
The C language binding of PHIGS
3.9 Memory management
The application shall allocate the memory needed for the data returned by the implementation. In general, the appli-
cation will allocate a C structure and pass a pointer to that structure to an inquiry routine which will then place
information into the structure. However, a number of inquiry functions return variable length data, the length of
which is not known a priori by the application.
These functions fall into two classes. One class of functions returns a simple, homogeneous list of elements. For
example, the function INQUIRE STRUCTURE IDENTIFIERS returns a list of the structure identifiers in use. The
other class returns complex, heterogeneous data structures. For example, the function INQUIRE LOCATOR DEV-
ICE STATE returns the device state which includes a locator data record; the data record can contain arbitrarily
complex implementation-defined data structures. The binding of these two classes of functions is described in detail
below.
Additional binding-specific errors which relate to memory management are described in 3.1 I .3.
3.9.1 Inquiry functions which return simple lists
Inquiry functions which return a list of elements are bound such that the application can inquire about a portion of
the list. This list portion is a subset of the implementation’s internal list and is called the application’s list. This
allows the application to process the implementation’s list in a piecewise manner rather than all at once.
The application allocates the memory for its list and passes that list to the implementation. The implementation
places the results of the inquiry into the list. In order to support this policy of memory management, three additional
parameters have been added to functions which return simple lists:
num elem appl list: An integer input parameter which is the size of the application’s list. The value of
a)
num-elem-appl-list indicates the number of list elements which will fit into the application’s list. A
valueof 0 is valid-and allows the application to determine the size of the implementation’s list (which is
returned via num elem imp1 list) without having the implementation return any of the elements of its
- - -
*.
start ind: An integer input parameter which is the starting index into the implementation’s list. (Index 0
b)
-
is the first element of both the implementation’s and application’s list.) start ind indicates the element in
the implementation’s list that is copied into index 0 of the application’s list. Elements are copied sequentially
from the implementation’s list into the application’s list until the application’s list is full or there are no more
elements in the implementation’s list.
If start ind is out of range, error number 2200 (PE START IND INVAL) is returned as the value of
- - -
the error indicator parameter.
num elem imp1 list: An output parameter which is a pointer to an integer. The implementation stores
C>
-
- -
into this parameter the number of elements that are in the implementation’s list.
Each function which returns a simple list has an output parameter list, which is a pointer to a structure with fields for
the number of elements in the list and a pointer to the elements in the list. The type of list depends upon the function
in which it is used. The implementation places the elements in the memory pointed to by list->elems and assigns the
number of elements in list->elems to list-xzum elems. If the implementation’s list is of zero length, no data is
placed in list->elems and list->num elems is set 6 zero.
-
3.9.2 Inquiry functions which return complex data structures
The data returned by the element content functions and the functions which return input device data records can be
complex in structure; they cannot be represented by a simple list of elements. It would be an onerous task for the
application to allocate and to prepare data structures for these routines. In order to facilitate the task of using these
inquiry functions, the binding defines a new resource, called a Store, to manage the memory for these functions.
A Store is used by the implementation to manage the memory needed by the functions which return complex data
structures. The Store resource is opaque to the application. The application does not know the structure of the Store
or how it is implemented. The ,Store is defined as a void *. The binding defines two new functions which create
ISO/IEC 9593-4: 1991(E)
The C language binding of PHIGS
pdel store) a
(CREATE STORE, bound as pcreate store) and destroy (DELETE STORE, bound as
- -
Store.
The semantics of the Store resource provide two levels of memory management: The implementation is responsible
for managing the memory at a low level because it uses, re-uses, allocates and deallocates memory from the system
in order to return information to the application. But the application is ultimately responsible for managing the
memory at a high level because it creates and destroys Stores.
A Store is passed as a parameter to a function returning complex data. Another parameter to this function is a
pointer to a pointer to a structure which defines the format of the returned data. The Store contains memory for the
structure and any additional memory referenced by fields within the structure. The application accesses the returned
data through its pointer to the structure; it does not use the Store to access the data.
For some functions, a Store is used to manage the memory for two or more distinct complex data structures. For
example, in the function INQUIRE PICK DEVICE STATE, the Store manages the memory for the pick filter, the
initial pick path, and the pick data record, all of which are returned to the application.
A Store continues to hold the information returned from the function until the Store is destroyed by the
pdel store function, or until the Store is used as an argument to a subsequent function which returns complex
data. At that time, the old information is replaced with the new. Thus multiple calls to functions overwrite the con-
tents of a Store. A Store only contains the results of the last function. An application may create more than one
Store.
This binding defines two new errors that can occur when using or creating a Store; these errors are described in
3.11.3. For most functions using a Store, these and other errors are returned via the “error indicator” parameter.
However, the functions RETRIEVE PATHS TO ANCESTORS, RETRIEVE PATHS TO DESCENDANTS and
ESCAPE do not have an error indicator parameter. For these functions, the error reporting mechanism is used when
an error is encountered. For these functions, the implementation shall, in addition to reporting the error, set the
pointer to the returned data to NULL when an error occurs.
The definitions for the functions CREATE STORE and DELETE STORE follow:
CREATE STORE
@-OR *, $9 *)
Parameters:
I
OUT error indicator
STORE
OUT store
Effect: Creates a Store and returns a handle to it in the parameter store. If the Store cannot be created, the store
parameter is set to NULL and the error indicator is set to one of the following error numbers:
002 Ignoring function, function requires state (PHOP, *, *, *).
2203 Ignoring function, error allocating Store.
Errors:
none
DELETE STORE @-OR *, *, *>
Parameters:
OUT error indicator I
IN/OUT store STORE
Effect:
Deletes the Store and all internal resources associated with it. The parameter store is set to NULL to sig-
nify that it is no longer valid. If an error is detected, the error indicator is set to the following error number:
002 Ignoring function, function requires state (PHOP, *, *, *).
Errors: none
ISO/IEC 9593=4:1991(E)
The C language binding of PHIGS
3.9.3 Meaning of the size of an element
The functions INQUIRE CURRENT ELEMENT TYPE AND SIZE and INQUIRE ELEMENT TYPE AND SIZE
return the size of an element. The size of an element is the size of a buffer, in bytes, that the application would have
to allocate in order to contain the element. If the application would not have to allocate any memory, then 0 is
returned.
3.10 Inquiries returning structure elements
PHIGS provides the ability for the application to inquire the contents of a structure element (through INQUIRE
CURRENT ELEMENT CONTENT and INQUIRE ELEMENT CONTENT). PHIGS also allows the application to
read in an archive file that can contain GDPs ‘(both GENERALIZED DRAWING PRIMITIVES and GENERAL-
IZED DRAWING PRIMITIVE 3’s) and GSEs (GENERALIZED STRUCTURE ELEMENTS) which are not sup-
ported by the implementation. Thus it is possible for the application to inquire the contents of a structure element
that contains a GDP or GSE data record that the implementation does not support.
In order to allow the inquiry of unsupported data records, the binding has introduced a field, called unsupp, to the
GDP and GSE data record structures. The type of this field is
Pdat a which is a structure containing a field for the
size of a block of data and another field for a pointer to the data. The unsupp field is used if the implementation
does not support a GDP or a GSE.
3.11 Error handling
3.11.1 Application defined error handlers
An application can define the error handling function for the PHIGS implementation via the utility function SET
ERROR HANDLER, which is bound as pset err hand. The definition for SET ERROR HANDLER is:
- -
1 * * *
SET ERROR HANDLER
9 7 9
( )
Parameters:
IN new error handling function Function
Function
OUT old error handling function
Effect: Sets the PHIGS error handling function ts new error handingfunction and returns the previous function in
old error handling function.
Errors: none
Application defined error handling functions accept the same arguments as the standard error handler. It may invoke
the standard error logging function perr log.
-
ISO/IEC 9592-l defines the initial error handling function to be perr hand; that is, the value of the parameter
old err hand points to perr hand when SET ERROR HANDLER is invoked for the first time.
- - -
When the application changes the error handling function, the implementation will invoke the new function when an
error is detected. If the application calls the default error handling function perr hand, perr-hand will
always call the default error logging function perr log; hand does not call-me error handling function
perr
- -
specified in SET ERROR HANDLER.
3.11.2 Error codes
This binding defines, in 6.2, a set of constants for the PHIGS error numbers. Each error constant begins with the
characters PE.
ISOhEC 959394: 1991(E)
The C language binding of PHIGS
3.11.3 C specific PHIGS errors
This binding defines the following additional errors, beyond the ones described in ISO/IEC 9592- 1.
Error Message
2200 Ignoring function, start index is out of range
Is issued when the start index is less than zero or larger than the last element in
the implementation list.
2201 Ignoring function, length of application's list is negative
Is issued when the length of the application’s list is less than zero.
2202 Ignoring function, enumeration type out of range
Is issued when a parameter value whose type is an enumeration is out range of
the enumeration.
2203 Ignoring function, error while allocating a Store
Is issued when an error is detected during CREATE STORE.
2204 error while allocating memory
Ignoring function,
for a Store
Is issued when a function using a Store is unable to allocate memory for the store.
3.12 Storage of two-dimensional data
3.12.1 Storage of matrices
ISO/IEC 9592-l represents transformations as 3x3 and 4x4 matrices. This part of ISO/IEC 9593 binds a PHIGS
3x3 matrix to the type Pmatrix and a PHIGS 4x4 matrix to the type Pmatrix3.
The elements of a PHIGS 3x3 matrix are:
abc
def
ghi
i 1
and these elements are stored such that:
m[O] [O] = a; m[O][l] = b; m[0][2] = c;
m[l] [O] = d; m[l] [l] = e; mw VI = f;
m[2][2] = i;
aa WI = g; m[2] [l] = h;
where m is of type Pmat rix.
The elements of a PHIGS 4x4 matrix are:
c
a b c d
e f g h
i j k 1
m n 0 p
b
and these elements are stored such that:
m[Ol [O] = a; m[O] [l] = b; m[O][2] = c; m[O][3] = d;
m[ll [O] = e; m[1][3] = h;
mD1 111 = f; m[ll 121 = g;
m[2] [O] = i; m[f] [1] = j; m[2][2] = k; m[2][3] = 1;
m[3] [O] = m; m[3] [l] = n; m[3][2] = 0;
m[31[131 = p;
I
ISOhEC 9593-4: 1991(E)
The C language binding of PHIGS
where m isof type Pmatrix3.
For example, in order to store the projection transformation defined by:
x -d/w’
y --+y’/w’
z + Z’IW’
in IWIGS 4x4 matrix, the values shall be stored such that:
x’
= P[Ol [wan + p[Ol m*y + p[Ol [a*2 + p[O] [3];
= P[11 [Olin + p[11 [:ll”y + PC11 [2l*z + p[l] [3];
Y'
Z’
= PM [01*X + pm ru*y + pm w1*z + p[2] [3];
w' =
PI31 [03*X + pr31 n1*y + p[31 c21*z + p[3] [3];
where p is of type Pmat rix3.
3.12.2 Storage of colour arrays
The entries for the Ppat rep data type shall be stored such that the colour index at the (i,j)-th entry of a DXxDY
array of colour indices is &en by:
colr-ind(i,j, = colr recbcolr array[i + DX*j];
- -
colr rect isoftype Ppat-rep and
-
colr rect.dims.size x = DX;
- -
colr-rect.dims.sizey = DY;
i = O,.,DX-1;
= O,.,DY-1;
j
ISOhEC 9593-4: 1991(E)
Function Abbreviation Table Tables
4 Tables
4.1 Abbreviation policy for construction of identifiers
The following policy is used to construct the identifiers for data types, structure fields, functions, and macros:
All identifiers in this part of ISO/IEC 9593 are abbreviated using the same abbreviations for every component
a)
and using underscores to denote blanks.
The plural of an expression is constructed by adding an “s” after its abbreviation; so, for example
...