ISO/IEC 8651-4:1995
(Main)Information technology — Computer graphics — Graphical Kernel System (GKS) language bindings — Part 4: C
Information technology — Computer graphics — Graphical Kernel System (GKS) language bindings — Part 4: C
Le système graphique GKS, ISO 7942:1994, spécifie un noyau graphique indépendant du langage. Pour être intégré dans un langage de programmation, GKS est inclus dans une couche dépendante du langage et obéissant aux conventions particulières de ce langage. La présente partie de l'ISO/CEI 8651 spécifie une couche dépendante du langage pour le langage C.
Technologies de l'information — Infographie — Interfaces langage avec GKS — Partie 4: C
General Information
Relations
Standards Content (Sample)
INTERNATIONAL ISO/IEC
STANDARD 8651-4
Second edition
1995-06-01
Information technology - Computer
graphics - Graphical Kerne1 System (GKS)
language bindings -
Part 4:
C
Technologies de I ’information - Infogt-aphie - Interfaces langage avec
GKS -
Partie 4: C
---------------------- Page: 1 ----------------------
ISO/IEC 8651-4:1995(E)
Contents
V
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vi
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
.......................................................................................................................................................
1 Scope
2
...........................................................................................................................
2 Normative references
3
.......................................................................................................................
3 The C language binding
3
................................................................................................
3.1 Classification and designation
3
..........................................................................................................
3.2 Functions versus macros
3
.......................................................................................................................
3.3 Character strings
3
...................................................................................................................
3.4 Function identifiers
3
3.5 Registration .
................................................................................................. 4
3.6 Identifiers for graphical items
4
3.7 Return values .
4
Headers .
3.8
4
3.8.1 gks.h .
4
3.8.2 gks compat.h .
5
..............................................................................................................
3.9 Memory management
5
3.9.1 Functions which return simple lists .
5
Functions which return complex data structures .
3.9.2
7
...........................................................................................................................
3.10 Error handling
7
Application supplied error handlers .
3.10.1
7
.................................................................................................................
3.10.2 Error Codes
7
...............................................................................................
3.10.3 C-specific GKS errors
7
............................................................................
3.11 Colour representations and specifications
7
...............................................................................................................
3.12 Colour characteristics
8
......................................................................................
3.13 Storage of multi-dimensional arrays
8
.............................................................................................
3.13.1 Storage of 2*3 matrices
8
.............................................................................
3.13.2 Storage of conics in 3*3 matrices
8
3.13.3 Storage of colour arrays .
8
.......................................................................................
3.14 Compatibility with the 1991 edition
-
9
4 Tables .
9
4.1 Abbreviation policy in construction of identifiers .
9
4.2 Table of abbreviations used .
13
4.3 Function names .
13
4.3.1 List ordered alphabetically by bound name .
20
4.3.2 List ordered alphabetically by GKS name .
28
5 .
Type definitions
28
..................................................................................................
5.1 Mapping of GKS data types
28
5.2 .
Environment-defined type definitions
29
.....................................................................
5.3 Implementation dependent type definitions
35
...................................................................
5.4 Implementation independent type definitions
91
6 Macro definitions .
91
6.1 Function identifiers .
91
6.1.1 In Order of appearance .
- -
95
6.1.2 In alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
0 ISO/IEC 1995
All rights reserved. Unless otherwise specified, no part of this publication may be
reproduced or utilized in any form or by any means, electronie or mechanical, including
photocopying and microfilm, without permission in writing from the publisher.
ISO/IEC Copyright Office l Case postale 56 l CH-121 1 Geneve 20 0 Switzerland
Printed in S witzerland
ii
---------------------- Page: 2 ----------------------
--
ISO/IEC 8651-4 : 1995(E)
0 ISO/IEC
99
6.2 Error Codes . . . . . . . . . . . . . . . . . . ‘.
104
6.3 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . “.
104
6.3.1 Linetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
104
6.3.2 Marker types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . “.
104
6.3.3 Hatch styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
104
6.3.4 Colour models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
105
6.3.5 Prompt and echo types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
105
6.3.6 Default Parameter of gopen gks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
106
7 C GKS function interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
106
Notational conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1
106
Workstation independent functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2
106
7.2.1 Control functions .
108
7.2.2 Output functions .
110
7.2.3 Design output functions .
113
7.2.4 Primitive attribute functions .
119
7.2.5 Normalization transformation functions .
120
NDC picture functions .
7.2.6
121
7.2.7 Metafile functions .
122
7.2.8 Picture part store functions .
124
7.2.9 Input functions .
7.2.10 Font and glyph functions . 131
131
7.2.11 Audit and playback functions .
132
7.2.12 Inquiry functions .
145
7.2.13 Utility functions .
148
7.3 Workstation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
148
7.3.1 Control functions Y.
155
7.3.2 Inquiry functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
172
7.3.3 Retrieval functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
7.3.4 Viewing Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
7.3.5 Colour Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.4 Segment functions and workstation activation functions
173
7.4.1 Segment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
176
7.4.2 Workstation activation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
176
7.4.3 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
177
I
Annexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
177
A Compiled GKS /C specification .
177
AS Data types in compilation Order .
223
A.2 Macros .
231
A.3 Function calls .
260
A.4 Compatibility layer .
271
..............................................................................................................................
B Sample programs
271
B.l STAR .
273
B.2 IRON .
280
.................................................................................................................
c Short function identifiers
280
In Order of appearance .
c.1
............................................................................................................ 287
c.2 In alphabetical Order
294
......................................................................................................................
D Memory management
294
...........................................................................................................................
D.l Introduction
294
.......................................................................................
D.2 Functions that return simple lists
............................................................ 295
D.2.1 Operationof ginq_list line inds
297
................................................................................ -
D.3 Functions that return structured dZa
298
Operationof gcreate store .
D.3.1
. . .
111
---------------------- Page: 3 ----------------------
0 ISOIIEC
ISO/IEC 8651-4 : 1995(E)
................................... 300
D.3.2 Operationof gincstroke-st and ginggat-rep
304
store .
D.3.3 Operation of gdel
307
..............................................................
E Compatibility with the 1991 editionof ISO/IEC 86514
edition . 307
E.l Comparison of this edition of ISO/IEC 86514 with the 1991
307
...............................................................
E.1.1 Changes in ISO/IEC 86514 data types
308
................................................................
E.1.2 Changes in ISO/IEC 86514 functions
309
........................................................................................................
E.2 The compatibility layer
309
................................................................................................
E.3 Theheader gks compat.h
-
309
............................................................................................
E.4 Datatypesin gks compat.h
-
309
.............................................................................................
E.4.1 Renamed data types
309
..............................................................................
E.4.2 Renamed fields of data types
310
...............................................................................................
E.4.3 Obsolete data types
314
E.5 Macros .
314
...................................................................................
E.6 Functions in the compatibility layer
314
Replaced functions .
E.6.1
317
Obsolete functions .
E.6.2
324
......................................................................................................................................
F Function lists
324
.....................................................................................................
F.l Alphabetic by GKS name
331
...............................................................................................
F.2 Alphabetic by binding name
iV
---------------------- Page: 4 ----------------------
0 ISO/IEC ISO/IEC 8651-4: 1995(E)
Forewsrd
ISO (the International Organization for Standardization) and IEC (the Inter-
national Electrotechnical Commission) form the specialized System for worldwide
standardization. National bodies that are members of ISO 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.
ISO and IEC technical committees collaborate in fields of mutual interest. Other
international organizations, governmental and non-governmental, in liaison with
ISO and IEC, also take part in the work.
In the field of information technology, ISO 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 865 l-4 was prepared by Joint Technical
Committee ISO/IEC JTC 1, Information technology, Subcommittee SC 24,
Computer graphics and image processing.
This second edition cancels and replaces the first edition (ISO/IEC 865 l-4: 199 l),
which has been technically revised.
ISO/IEC 865 l-4 consists of the following Parts, under the general title
Graphical Kerne1 System (GKS)
Information technology - Computer graphics -
language bindings:
- Part 1: FORTRAN
- Part 2: Pascal
- Part 3: Ada
- Part 4: C
Annexes A to F of this part of ISO/IEC 8651 are for information only.
---------------------- Page: 5 ----------------------
ISO/IEC 8651-4: 1995(E) 0 ISO/IEC
Introduction
The Graphical Kerne1 System (GKS) functional description is registered as ISO/IEC 7942-1:1994. As
explained in the Scope and Field of Application of ISO/IEC 7942-1, that International Standard 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 8651 is to define a Standard binding for the C Computer programming
language.
Vl
---------------------- Page: 6 ----------------------
INTERNATIONAL STANDARD 0 ISO/IEC ISO/IEC 8651-4:1995(E)
Information technology - Computer graphics -
Graphical Kerne1 System (GKS) language bindings -
Part 4:
C
1 Scope
The Graphical Kerne1 System (GKS), ISO/IEC 7942-1: 1994 , specifies a language independent nucleus of
a graphics System. For integration into a programming language, GKS is embedded in a language depen-
dent layer obeying the particular conventions of that language. This part of ISOLIEC 8651 specifies such a
language dependent layer for the C language.
---------------------- Page: 7 ----------------------
ISO/IEC 8651-4 : 1995(E) 0 ISO/IEC
2 Normative references
The following Standards contain provisions which, through reference in this text, constitute provisions of
this part of ISO/IEC 8651. 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 8651 are encouraged to investi-
gate the possibility of applying the most recent editions of the Standards indicated below. Members of IEC
and ISO maintain registers of currently valid International Standards.
ISO/IEC 7942-1: 1994, Information technology - Computer graphics and image processing - Graphical
Kerne1 System (GKS) - Part 1 : Functional description.
ISO/IEC 9899:1990, Programming Zanguages - C.
ISO/IEC TR 9973: 1994, Information technology - Computer graphics and image processing - Procedures
for registration of graphical Items.
2
---------------------- Page: 8 ----------------------
I
--
0 ISO/IEC
ISO/IEC 8651-4 : 1995(E)
3 The C language binding
The C language binding of GKS shall be as described in clauses 3 to 7.
3.1 Classification and designation
This part of ISO/IEC 8651 incorporates the rules of conformance defined in the GKS Standard (ISO/IEC
7942-1) for GKS implernentations, with those additional requirements specifically defined for C bindings in
GKS.
The following criteria shall determine conformance of an implementation to this part of ISO/IEC 8651:
In Order to conform, an implementation of the C binding of GKS shall implement GKS as specified in
ISO/IEC 7942-1. It shall make visible all of the declarations in the C binding specified in this part of
ISO/IEC 8651 for a specific level of C.
Thus, for example, the sy ntax of the function names shall be precisely as specified in the binding and
Parameters shall be of the data types stated in the binding.
3.2 Functions versus macros
An implementation may Substitute macros for functions. However, the macros shall be designed so that
side-effects work properly. In general, a macro cannot be used to replace the error handling function
gerr hand. See also 3.10.
-
3.3 Character strings
The C language represents Character strings as an array of characters terminated by the null Character (i.e.
’ \ 0 ’ ). This means that the null Character is not usable as a printable Character.
3.4 Function identifiers
The function names of GKS are all mapped to C functions which begin with the letter g. Words and
phrases used in the GKS function names are often abbreviated in the representation and are always
separated with the underscore Character ll-ll. The set of such abbreviations is given in 4.2, and the result-
ing C function names are listed in 4.3. For example, the abbreviation for the GKS function DELETE SEG-
MENT FROM WORKSTATION is gdel seg WS. del, seg, and WS are abbreviations for
- -
DELETE, SEGMENT, and WORKSTATION. The conjunctive FROM is mapped to the null string.
The C language (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.
Implernentations which run in environments where two distinct C internal identifiers would be equivalent,
if they were both external identifiers, shall include a set of Object-like macros in the header which equate
the long names to a set of short names. A possible set of short names for a Compiler that accepts only 8
characters for external definitions may be found in annex C.
3.5 Registration
ISO/IEC 7942 reserves certain value ranges for registration’ as graphical items. The registered graphical
items will be bound to the C programming language (and other programming languages). The registered
item binding will be consistent with the binding presented in this part of ISO/IEC 8651.
’ For the purpose of this part of ISO/IEC 8651 and according to the rules for the designation and Operation of registration
authorities in the ISO/IEC Directives, the ISO/IEC council has designated the National Institute of Standards and Technol-
ogy (Institute of Computer Sciences and Technology), A-266 Technology Building, Gaithersburg, MD 20899, USA to act
as registration authority.
---------------------- Page: 9 ----------------------
0 ISO/IEC
ISO/IEC 8651-4 : 1995(E)
3.6 Identifiers for graphical items
Generalized Drawing Primitives and Escape functions are referenced via identifiers. This part of ISO/IEC
8651 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 ggdp and gescape.
An implementation may also represent GDPs and Escapes as separate functions, but this is not required.
There arc two formats for these identifiers. One format is for registered GDPs and Escapes and the other
format is for unregistered GDPs and Escapes.
The format for registered @DP identifiers is:
#def ine GGDP-Rn /* where 9P is the registered GDP
W
identifier */
The format for unregistered GDP identifiers is:
#define GGDP-Un d* where lnf is implementation
t-n)
dependent */
The format for registered Escape function identifiers is:
#def ine GESCAPE-Rn where %' is the registered
(n) /*
Escape identifier */
The format for unregistered Escape function identifiers is:
#define GESCAPEJJn (On) where In' is implementation
/*
dependent *%
3.7 Return values
All GMWC functions have return value void.
3.8 Headers
3.8.1 gks. h
C provides a mechanism to access information stored in a header via the #include preprocessing direc-
tive. Clause 5 of this part of ISO/IEC 8651 describes the data types that shall be defined in the header
gks . h which shall be included in any application program that intends to use GKS via the C binding.
This part of ISO/IEC 8651 uses the data type size t (inter alia as a field in the data type Gdata). The
-
type size-t is environment-defined (i.e. unsigned long or unsigned int) andisdefinedinthe
headers , , , , .
Additional implementation-dependent items may be placed in this header if needed. These items should
Start with the sentinel “G” or “g ”, as far as applicable.
The header gks . h shall also contain external declarations for all GKS/C functions because they have a
void return type. For example, the declaration for the function gopen-gks would look like this:
extern void
gopen-gks(const char *err-file, size-t memory);
3.8.2 gks
compat.h
-
For application programs which used to run on top of the 1991 edition of this part of HSO/IEC, the header
gks-compat . h is provided. gks-compat . h includes GKS/C data types that are no longer supported,
as well as external declarations for all GIWC functions that are no longer supported. Implernentations of
this part sf ISO/IEC 8651 shall support these functions in a compatibility layer, according to the guidelines
in Annex G of ISO/IEC 7942-1: 1994.
4
---------------------- Page: 10 ----------------------
0 ISOIIEC ISO/IEC 8651-4 : 1995(E)
3.9 Memory management
The application shall allocate the memory needed for the data returned by the implementation. In general,
the application 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 items.
For example, the function INQUIRE LIST OF MARKER INDICES returns a list of the available marker
indices. The other class returns complex, heterogeneous data structures. For example, the function
INQUIRE GKS STATE LIST ENTRY returns a piece of the GKS state which may include several data
structures of different length. The binding of these two classes of functions is described in detail below.
Subclause 3.10 describes the errors that tan be invoked during execution of functions which use the
memory management policy.
3.9.1 Functions which return simple lists
Inquiry functions which return a list of items are bound such that the application tan inquire about a por-
tion of the list. This list is a subset of the implementation ’s internal list and is called the application ’s list.
This allows the appli
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.