ISO/IEC 8651-4:1991
(Main)Information technology — Computer graphics — Graphical Kernel System (GKS) language bindings — Part 4:
Information technology — Computer graphics — Graphical Kernel System (GKS) language bindings — Part 4:
Technologies de l'information — Infographie — Système graphique de base (GKS) — Interface langage — Partie 4:
General Information
Relations
Standards Content (Sample)
ISOIIEC
I N TE R NAT I O NA L
STANDARD
8651 -4
First edition
1991 - 12- 1 5
Information technology - Computer graphics -
Graphical Kernel System (GKS) language
bindings -
Part 4:
C
Technologies de I'inforniation - infographie - Système graphique de
base (GKS) - interface langage -
Partie 4: C
Reference number
ISO/IEC 8651 -4A991 (E)
---------------------- Page: 1 ----------------------
ISOhEC 8651-4 : 1991(E)
Contents
.................................................................................................................................
scop . _ 1
1
...............................................................................................................................
2 Normative references 2
The C Language Binding of GKS . 3
3
.-I
Conform~ce . 3
3.1
Functiom versus Macros . 3
3.2
Character Strings . 3
3.3
Function Identifiers . 3
3.4
Registration . 3
3.5
Identifiers for Graphical Items . 4
3.6
Remm Values . 4
3.7
Header Files . 4
3.8
Memory Management . 4
3.9
Functions which Return Simple Lists . 5
3.9.1
3.9.2 Functions which Remm Complex Data structures . 5
.............................................................................................................................
3.10 Error Hadling 6
..............................................................................
6
3.10.1 Application Supplied Error Handlers
3.10.2 Error Codes . 7
3.10.3 C-specific GKS errors . 7
Colour Representatio ns . 7
3.11
Storage of Multi-dimensional Arrays . 8
3.12
3.12.1 Storage of 2*3 Matices . 8
3.12.2 Storage of Colour Arrays . 8
Tables and Abbreviations .
4
Abbreviation Policy in Construction of Identifiers . 9
4.1
4.2 Abbreviations Used . 9
4.3 Function Names . 13
...............................................................
4.3.1 List Ordered Alphabetically by Bound Name 13
4.3.2 List Ordeed Alphabetically by GKS Name . 17
List Ordered Alphabetically by Bound Name within Level . 21
4.3.3
Type Definitions . 27
5
Mapping of GKS data types . 27
5.1
Environmental Type Definitions . 27
5.2
Implementation Dependent Type Definitions . 27
5.3
5.4 Implementation Independent Type Definitions . 34
Macro Definitions . 49
6
6.1 Function identifiers . 49
6.2 Error Codes . 51
6.3 Miscellaneous Macros . 57
6.3.1 Lineiypes . 57
6.3.2 Marker Types . 57
6.3.3 Prompt and Echo Types . 57
6.3.4 Default Parameters of OPEN GKS . 57
C GKS Function Interface . 58
7
7.1 Notational Conventions . 58
7.2 ConiIol Functions . 58
7.3 output Functions . 60
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 .
ISOAEC Copyright Office 0 Case postale 56 0 CH-121 1 Genève 20 0 Switzerland
Printed in Switzerland
---------------------- Page: 2 ----------------------
ISO/IEC 8651-4 : 1991(E)
Output Attribute Functions . 61
7.4
7.4.1 Workstation Independent Primitive Attributes . 61
7.4.2 Workstation Attributes . 64
7.5 Transformation Functions . 65
7.5.1 Normalization Transformation . 65
7.5.2 Workstation transformation . 66
7.6 Segment Functions . 66
7.6.1 Segment Manipulation Functions . 66
7.6.2 Segment Attribute Functions . 68
.......................................................................................................................... 68
7.7 Input Functions
7.7.1 Initialization of Input Devices Functions . 68
7.7.2 Setting the Mode of Input Devices Functions . 70
7.7.3 Request Input Functions . 71
7.7.4 Sample Input Functions . 73
7.7.5 Event Input Functions . 74
7.8 Metaile Functions . 75
7.9 Inquiry Functions . 76
7.9.1 Inquiry Functions for Operating State Value . 76
7.9.2 Inquiry Functions for GKS Description Table . 76
7.9.3 Inquiry Functions for GKS State List . 77
7.9.4 Inquiry Functions for Workstation State List . 84
7.9.5 Inquiry Functions for Workstation Description Table . 91
7.9.6 Inquire functions for the Segment State List . 98
7.9.7 Pixel Inquiries . 98
7.9.8 Inquiry Functions for Error State List . 99
7.10 Utility Functions . 99
7.10.1 Utility Functions in GKS . 99
7.10.2 Binding Specific Utilities . 100
7.11 Error Handlin ç! . 100
.
A
Compiled GKS/C Specification . 102
B
Sample Programs . 14j
B.l STAR Program . 14j
B.2 IRON Program . 147
B.3 MAP Program . 1j4
B.4 MANIPULATE Program . 156
B.5
SHOW LINE Program . 162
C Metafîle Items . 168
D Short Function Identifiers . 170
E Memory Management . 175
E.l Introduction . 175
E.2 Functions That Return Simple Lists . 175
E.2.1 Operation of ginq-list-line-inds . 175
E.3 Functions That Return Structured Data . 178
E.3.1 Operation of gcreate-store . 179
E.3.2
Operation of ginq-stroke-st and ginQpat-rep . 181
E.3.3 Operation of gdel-store . 185
F Function Lists . 188
F.l Alphabetic by GKS Name . 188
F.2 Alphabetic by Binding Name . 192
üi
---------------------- Page: 3 ----------------------
I
ISOhEC 8651-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
of International Standards through technical
participate in the development
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
1. Draft International Standards adopted by
technical committee, ISO/IEC JTC
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 1-4 was prepared by Joint Technical
Committee ISO/iEC JTC 1, Information fechnology.
ISO/iEC 8651 consists of the following parts, under the general title Information
technology - Computer graphics - Graphical Kernel System (GKS) language
bindings:
- Part 1: FORTRAN 77
- Part 2: PASCAL,
- Part3:ADA
- Part4: C
Annexes A to F of this part of ISO/IEC 865 1 are for information only.
iv
---------------------- Page: 4 ----------------------
ISO/IEC 8651-4 : 1991(E)
Introduction
The Graphical Kernel System (GKS) functional description is registered as IS0 7942 : 1985. As explained
of IS0 7942, that International Standard is specified in a language
in the Scope and Field of Application
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.
V
---------------------- Page: 5 ----------------------
INTERNATIONAL STANDARD ISO/IEC 8651-4:1991(E)
Information technology - Computer graphics -
Graphical Kernel System (GKS) language bindings -
Part 4:
C
1 Scope
The Graphical Kernel System (GKS), IS0 7942 : 1985 , specifies a language independent nucleus of a
graphics system. For integration into a programming language, GKS is embedded in a language dependent
layer obeying the particular conventions of that language. This part of ISODEC 8651 specifies such a
language dependent layer for the C language.
1
---------------------- Page: 6 ----------------------
ISOhEC 8651-4 : 1991(E) GKSIC
2 Normative references
The following standards contain provisions which, through reference in this text, constitute provision of
this part of ISO/IEC 8651. At the time of publication, the editions indicated were valid. All standards are
subject to revisions, and parties to agreements based on this part of ISO/IEC 865 1 are encouraged to inves-
tigate the possibility of applying the most recent editions of the standards indicated below. Members of
IEC and IS0 maintain registers of currently valid International Standards.
IS0 7942:1985, Information processing systems - Computer graphics - Graphical Kernel System (GKS)
functional description.
ISO/IEC 865 1-1: 1988, Information processing systems - Computer graphics - Graphical Kernel System
(GKS) - language bindings - Part 1 : FORTRAN.
ISO/IEC 88064: 1991, Information technology - Computer graphics - Graphical Kernel System for Three
Dimensions (GKS3D) language bindings - Part 4 : C.
ISO/IEC 9899:1990, Programming languages - C.
ISO/IEC TR 9973: 1988, Information processing - Procedures for registration of graphical items.
2
---------------------- Page: 7 ----------------------
GKS/C ISO/IEC 8651-4 : 1991(E)
3 The C Language Binding of GKS
The C language binding of GKS shall be as described in clauses 3,4,5 and 6.
3.1 Conformance
This part of ISO/IEC 8651 incorporates the rules of conformance defined in the GKS Standard (IS0 7942)
for GKS implementations, 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 a specific level of
GKS as specified in IS0 7942. It shall make visible all of the declarations in the C binding specified in
this part of ISO/iEC 8651 for that same level of GKS and all lower levels and for a specific level of C.
Thus, for example, the syntax of the function names shali 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 shali 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.
\O ). 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 "-". 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 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.
Implementations which run in environments where two distinct C internai identifiers would be equivalent,
if they were both external identifiers, shall include a set of #de£ ines in the header file which equate the
long names to a set of short names. A possible set of short names for a compiler that accepts only eight
characters for external definitions may be found in annex D.
3.5 Registration
IS0 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 ISODEC 8651.
')For the purpose of this part of ISO/IEC 8651 and according to the rules for the designation and operation of registration
IS0 and JEC councils have designaied the National Institute of Standards and
authorities in the ISO/lEC Directives, the
Technology (institute of Computer Sciences and Technology), A-266 Technology Building, Gaithersburg, MD 20899,
USA to act as registration authority.
3
---------------------- Page: 8 ----------------------
ISOhEC 8651-4 : 1991(E) GKS/C
The C Language Binding of GKS
Identifiers for Graphical Items
3.6 Identifiers for Graphical Items
Generalized Drawing Primitives and Escape functions are referenced via identifiers. This part of ISOflEC
8651 specifies the fonnat of the identifiers but it does not specify the registration of the identifiers. The
identifiers m 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 are 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 GDP identifiers is:
#define GGDP-Rn (n) /* Inr is the registered GDP id. */
The format for unregistered GDP identifiers is:
#define GGDP-Un (-n) /* Inr is implementation dependent */
The format for registered Escape function identifiers is:
#define GESCAPE-FUI (n) /* ,nr is the registered Escape id. */
The format for unregistered Escape function identifiers is:
#define GEÇCAPE-Un (-n) /* ,nr is implementation dependent */
3.7 Return Values
Ail GKS/C functions return void.
3.8 Header Files
C provides a mechanism to allow external files to be included in a compilation. Clause 5 of this part of
ISOflEC 8651 describes the data types that shall be defined in the file gks . h which should be included in
any application program that intends to use GKS via the C binding.
Gdata). The type
This part of ISO/iEC 8651 uses the data type size-t (as a field in the data type
size-t is environment-dependent (e.g. int, long int, unsigned int) and is defined in the file
. Therefore the file gks . h shali also include the file .
Additional implementation-dependent items may be placed in this file if needed. These items should start
with the sentinel “G’ or “g”, as far as applicable.
The file gks . h shaii also contain external declarations for ali GKS/C functions because they return
void. For example, the declaration for the function gopen-gks would look like this:
extern void gopen-gks(char *err-file, size-t mem-units);
3.9 Memory Management
The application shall aliocate 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
wiil 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 faii into two classes. One class of functions returns a simple, homogeneous, list of items.
For example, the function INQUIRE SET OF SEGMENT NAMES returns a list of the segment names in
use. The other class returns complex, heterogeneous data structures. For example, the function INQUIRE
LOCATOR DEVICE STATE returns the device state which includes a locator data record; the data record
of these two classes
can contain arbitrarily complex implementation-defined data structures. The binding
3.10 describes the errors that can be invoked during
of functions is described in detail below. Subclause
execution of functions which use the memory management policy.
4
---------------------- Page: 9 ----------------------
GKS/C ISO/IEC 8651-4 : 1991(E)
The C Language Binding of GKS Memory Management
3.9.1 Functions which Return Simple Lists
Inquiry functions which return a list of items are bound such that the application can inquire about a por-
tion of the list. This list is a subset of the implementation’s internai list and is called the application’s list.
This allows the application to process the implementation’s list in a piecewise manner rather than ail at
once.
The application allocates the memory for a list and passes that list to the implementation. The implementa-
tion 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 lists:
a) nun-elemsappl-list: An integer input parameter which is the length of the application’s list.
The value of nun-elems-appï-iist indicates the number of items (i.e. list elements) which will
fit into the application list. A value of O is valid and allows the application to determine the size of the
implementation’s list (which is returned via nun-elems-impl-list) without having the imple-
mentation return any of the elements of its list. If nun-elemsappl-list is negative,
GE-APPL-LIST-LENGTH-LT - ZERO is returned as the vdue of the error indicator parameter.
b) start-ind: An integer input parameter which is an index into the implementation’s list. (Index O is
the first element of both the implementation’s and application’s list.) start-ind indicates the first
item in the implementation’s list that is copied into index O of the application’s list. Items are copied
sequentiaiiy from the implementation’s list into the application’s list until the application’s list is full or
there are no more items in the implementation’s list. If start-ind is out of range, error
GE-START-IND-INVAL is returned as the value of the error indicator parameter.
c) nun-eiems-impl-list: An output parameter which is a pointer to an integer. The implementation
stores into this parameter the number of items that are in the implementation’s list.
In annex E, a possible underlying mechanism is described.
3.9.2 Functions which Return Complex Data Structures
The data returned by the ESCAPE function and the functions which return input device data records or pat-
tern tables can be complex in structure. They cannot be represented by a simple list of items. It would be an
onerous task for the application to have to allocate and prepare data structures for these routines. In order
to facilitate this task of using these inquiry functions, the binding defines a new resource, called a Store, to
manage the memory for these functions.
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 * . This part of ISO/IEC 8651 defines two new
functions which create (in CREATE STORE, bound as gcreate - store) and delete (in DELETE
STORE, bound as del-store) a Store.
A Store is used by the implementation to manage the memory needed by the functions which return com-
plex data structures. Without specifying an implementation of a Store, it is safe to say that it will contain
and control memory needed to hold the data returned by these functions and also contain some bookkeep-
ing information about the contents and size of the memory.
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, reuses, allocates and deaiiocates
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 deletes Stores.
A Store is passed as a parameter to a function returning complex data structures. 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.
A Store continues to hold the information from the function until the Store is deleted by the DELETE
STORE function or until the Store is used as an argument to a subsequent function, which returns complex
5
---------------------- Page: 10 ----------------------
ISOhEC 8651-4 : 1991(E) GKS/C
Memory Management The C Language Binding of GKS
data structures. At that time, the old information is replaced with the new. Thus multiple calls to functions
overwrite the contents of a Store. A Store oniy contains the results of the last function.
This part of ISO/IEC 8651 defmes two new errors that can occur when using or creating a Store; these
errors are described in 3.10.3. For most functions using a Store, these and other errors are returned via the
"error indicator" parameter. However, the function ESCAPE does not have an error indicator parameter.
For this function, the error reporting mechanism is used when an error is encountered. For this function, the
implementation shall, in addition to reporting the error, set the pointer to the returned data to NULL when
an error occurs. See the binding of these functions for more information.
The definitio
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.