Information technology -- Computer graphics -- Graphical Kernel System (GKS) language bindings

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

General Information

Status
Published
Publication Date
14-Jun-1995
Current Stage
9020 - International Standard under periodical review
Start Date
15-Jul-2021
Ref Project

RELATIONS

Buy Standard

Standard
ISO/IEC 8651-4:1995 - Information technology -- Computer graphics -- Graphical Kernel System (GKS) language bindings
English language
339 pages
sale 15% off
Preview
sale 15% off
Preview

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:
Technologies de I ’information - Infogt-aphie - Interfaces langage avec
GKS -
Partie 4: C
---------------------- Page: 1 ----------------------
ISO/IEC 8651-4:1995(E)
Contents

Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ................................

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..........................

.......................................................................................................................................................

1 Scope

...........................................................................................................................

2 Normative references

.......................................................................................................................

3 The C language binding

................................................................................................

3.1 Classification and designation

..........................................................................................................

3.2 Functions versus macros

.......................................................................................................................

3.3 Character strings

...................................................................................................................

3.4 Function identifiers

3.5 Registration ................................................................................................................................

................................................................................................. 4

3.6 Identifiers for graphical items

3.7 Return values .............................................................................................................................

Headers ......................................................................................................................................

3.8

3.8.1 gks.h .........................................................................................................................

3.8.2 gks compat.h .........................................................................................................

..............................................................................................................

3.9 Memory management

3.9.1 Functions which return simple lists .......................................................................

Functions which return complex data structures ...............................................

3.9.2

...........................................................................................................................

3.10 Error handling

Application supplied error handlers ......................................................................

3.10.1

.................................................................................................................

3.10.2 Error Codes

...............................................................................................

3.10.3 C-specific GKS errors
............................................................................
3.11 Colour representations and specifications

...............................................................................................................

3.12 Colour characteristics

......................................................................................

3.13 Storage of multi-dimensional arrays

.............................................................................................

3.13.1 Storage of 2*3 matrices
.............................................................................
3.13.2 Storage of conics in 3*3 matrices

3.13.3 Storage of colour arrays ...........................................................................................

.......................................................................................

3.14 Compatibility with the 1991 edition

4 Tables ......................................................................................................................................................

4.1 Abbreviation policy in construction of identifiers ...............................................................

4.2 Table of abbreviations used .....................................................................................................

4.3 Function names .......................................................................................................................

4.3.1 List ordered alphabetically by bound name .......................................................

4.3.2 List ordered alphabetically by GKS name ...........................................................

5 ...................................................................................................................................

Type definitions

..................................................................................................

5.1 Mapping of GKS data types

5.2 .................................................................................

Environment-defined type definitions
.....................................................................
5.3 Implementation dependent type definitions
...................................................................
5.4 Implementation independent type definitions

6 Macro definitions ................................................................................................................................

6.1 Function identifiers .................................................................................................................

6.1.1 In Order of appearance ...........................................................................................

- -

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
---------------------- Page: 2 ----------------------
ISO/IEC 8651-4 : 1995(E)
0 ISO/IEC

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

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
---------------------- 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.
---------------------- 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:
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.
---------------------- Page: 8 ----------------------
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
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.
---------------------- 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.