ISO/IEC 8806-4:1991
(Main)Information technology — Computer graphics — Graphical Kernel System for Three Dimensions (GKS-3D) language bindings — Part 4: C
Information technology — Computer graphics — Graphical Kernel System for Three Dimensions (GKS-3D) 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, E and F are for information only.
Technologies de l'information — Infographie — Interfaces de langages pour GKS (Graphical Kernel System) pour trois dimensions — Partie 4: C
General Information
Standards Content (Sample)
ISOIIEC
INTERNATICNAL
STANDARD 8806-4
First edition
1991-12-15
-.-.------_
-. -----
Information technology - Computer graphics -
Graphical Kerne1 System for Three Dimensions
(GKS-3D) language bindings A
Part 4:
c
Technologies de I’information -. Infographie - Interfaces de langages
pour GKS (Graphical Kerne1 System) pow trois dimensions -
Partie 4: C
--
----
---pmwrz .__._.___-.-__ -.-.,----,----.
-- --
- --- .--
--
-- ---
---
-- _-
- Z
= =
-
=
=
= 5
Z
Z -1 i
5
=
5 =
=
E =
Reference number
= =
C C
-- --
--
- ---- ----- _
---- --.- - ---. - ---------- - .____ ISO/1 EC 8806-4: 199 1 (E)
___ ____ -_ -_-_ --_- 4fzf- -.-.-. --.
---------------------- Page: 1 ----------------------
ISO/IEC8806=4:199l(E)
Contents
1
scope .
1
2
2 Normative references .
3
. . . . . . . . . . . . . .t.
3 The C Language Binding of GKS-3D
3
3.1 Conformance .
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
3.8 Header Files .
4
3.9 Memory Management .
5
3.9.1 Functions which Return Simple Lists .
........................................................ 5
3.9.2 Functions which Return Complex Data Structures
6
Error Handling .
3.10
6
3.10.1 Application Supplied Error Handlers .
7
......................................................................................................................
3.10.2 Error Codes
7
...............................................................................................
3.10.3 C-specific GKS-3D errors
7
3.11 Colour Representations .
.......................................................................................... 8
3.12 Storage of Multi-dimensional Arrays
8
3.12.1 Storage of 2*3 Matrices .
8
3.12.2 Storage of 3*4 Matrices .
8
3.12.3 Storage of 4*4 Matrices .
8
3.12.4 Storage of Colour Arrays .
9
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
19
...........................................................
4.3.2 List Ordered Alphabetically by GKS-3D Name
25
..........................................
4.3.3 List Ordered Alphabetically by Bound Name within Level
32
....................................................................................................................................
Type Definitions
................................................................................................ 33 d
5.1 Mapping of GKS-3D data types
................................................................................................ 32
5.2 Environmental Type Definitions
........................................................................... 33
5.3 Implementation Dependent Type Definitions
......................................................................... 44
5.4 Implementation Independent Type Definitions
65
Macro Definitions .
65
6.1 Function identifiers .
68
6.2 Error Codes .
75
6.3 Miscellaneous Macros .
75
6.3.1 Linetypes .
75
6.3.2 Marker Types .
75
...............................................................................................................
6.3.3 Colour Models
75
.................................................................................................
6.3.4 Prompt and Echo Types
................................................................................ 76
6.3.5 Default Parameters of OPEN GKS
77
7 C GKS-3D Function Interface .
77
7.1 Notational Conventions .
77
7.2 Control Functions .
79
7.3 Output Functions .
0 ISO/IEC 1991
All rights reserved. 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 l Switzerland
Printed in Switzerland
---------------------- Page: 2 ----------------------
ISO/IEC8806-4:1991(E)
7.4 Output Attribute Functions
........................................................................................................ 81
7.4.1 Workstation Independent Primitive Attributes
.............................................................. 81
7.4.2 Workstation Attributes . 85
7.5 Transformation Functions
.......................................................................................................... 87
7.5.1 Normalization Transformation . 87
7.5.2 View transformation functions . 88
7.5.3 HLHSR functions . 88
7.5.4 Workstation transformation . 89
7.6 Segment Functions . 89
7.6.1 Segment Manipulation Functions . 89
......................................................................................... 91
7.6.2 Segment Attribute Functions
.......................................................................................................................... 92
7.7 Input Functions
...................................................................... 92
7.7.1 Initialization of Input Devices Functions
............................................................... 95
7.7.2 Setting the Mode of Input Devices Functions
................................................................................................
7.7.3 Request Input Functions 96
7.7.4 Sample Input Functions . 98
7.7.5 Event Input Functions . 100
7.8 MetafYile Functions . 102
7.9 Inquiry Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.9.1 Inquiry Functions for Operating State Value . 102
7.9.2 Inquiry Functions for GKS-3D Description Table . 103
Inquiry Functions for GKS-3D State List . 103
7.9.3
.............................................................. 112
7.9.4 Inquiry Functions for Workstation State List
................................................ 124
7.9.5 Inquiry Functions for Workstation Description Table
............................................................... 135
7.9.6 Inquire functions for the Segment State List
136
7.9.7 Pixel Inquiries .
137
7.9.8 Inquiry Functions for Error State List .
7.10 Utilitj Functions . 137
7.10.1 Utility Functions in GKS-3D . 137
7.10.2 Binding Specific Utilities . 138
7.11 Error Handling . . . . . . . . . . . . . . . t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
A Compiled GKS-3D/C Specifkation . 141
B Sample Programs . 204
B.l STAR Program . 204
B.2 IRON Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.- 906
B.3 MAP Program . 213
B.4 MANIPULATE Program . 215
B.5 SHOW LINE Program . 221
B.6 DODECA Program . 226
C Metafile Items . 231
D Short Function Identifiers . 233
240
E Memory Management .
E.l 240
Introduction .
E.2 . 240
Functions That Return Simple Lists
240
E.2.1 Operationof ginq_list line inds .
243
E.3 Functions That Return Structured Data . -
244
E.3.1 Operation of gcreate store .
E.3.2 Operationof ginestroke st and ginq_pat rep . 246
-
E.3.3 Operation of gdel store . - 250
-
F Function Lists . 253
F.1 . 253
Alphabetic by GKS-3D Name
F.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Alphabetic by Binding Name
. . .
Ill
---------------------- Page: 3 ----------------------
ISO/IEC 8806-4 : 1991(E)
Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Com-
mission) together form a System for worldwide standardization as a whole. National bodies that are
members of ISO or IEC participate in the development of International Standards through technical com-
mittees established by the respective organization to deal with the fields of technical activity. ISO and IEC
technical committees colIaborate in fields of mutual interest. Other international organizations, govem-
mental and non-govemmental, in liaison with ISO and IEC, also take part in the werk.
In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC
JTCl. 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 8806-4 was prepared by Joint Technical Committee ISO/IEC JTCl, 1@or-
mation technology.
ISO/IEC 8806 consists of the following parts, under the general title
Information technology - Computer graphics - Graphical Kernel System for Three Dimensions (GKS3D)
language bindings -
Part 1: FORTAN
Part 2: PASCAL
Part 3: ADA
Part4: C
Annexes A to F of this part of ISO/IEC 8806 are for information orily.
iv
---------------------- Page: 4 ----------------------
ISO/IEC 8806-4 : 1991(E)
Introduction
The Graphical Kerne1 System for Three Dimensions (GKS3D) functional description is registered as ISO
8805 : 1988. As explained in the Scope and Field of Application of ISO 8805, that International Standard
is specified in a language independent manner and needs to be embedded in language depcndent layers
(language bindings) for use with particular programming languages.
The purpose of this part of ISO/IEC 8806 is to define a Standard binding for the C Computer programming
language.
Some functions in ISO 8805 also appear in the Graphical Kerne1 System (GM) functional description
(ISO 7942). The binding of those functions in this part of ISO/IEC 8806 is the same as in ISO/IEC 8651-4,
the C language binding of GKS.
---------------------- Page: 5 ----------------------
This page intentionally left blank
---------------------- Page: 6 ----------------------
INTERNATIONAL STANDARD ISOAEC 8806=4:1991(E)
Information technology - Computer graphics -
Graphical Kerne1 System for Three Dimensions
(GKS-3D) language bindings -
Part 4:
C
1 Scope
The Graphical Kerne1 System for Three Dimensions (GKS-3D), ISO 8805 : 1988 , specifies a language
independent nucleus of a graphics System. For integration into a programming language, GKS-3D is
embedded in a language dependent layer obeying the particular conventions of that language. This part of
ISO/IEC 8806 specifies such a language dependent layer for the C language.
1
---------------------- Page: 7 ----------------------
ISO/IEC 8806-4 : 199l(E) GKS=3D/C
2 Normative references
The following Standards contain provisions which, through reference in this text, constitute Provision of
this part of ISO/IEC 8806. 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 lSO/IEC 8806 are encouraged to inves-
tigate 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.
- Graphical Kerne1 System (GKS)
ISO 794211985, Information processing systems - Computer graphics
functional description.
- Graphical Kerne1 System (GKS)
ISO/IEC 8651-4:1991, Information technology - Computer graphics
language bindings - Part 4 : C.
ISO 880511988, Information processing Systems - Computer graphics - Graphical Kerne1 System for
Three Dimensions (GKS-3D) functional description.
ISO/IEC 8806- 1: 1991, Information processing systems - Computer graphics - Graphical Kerne1 Svstem
e
for three dimensions (GKS-3D) - language bindings - Part 1 : FORTRAN.
ISO/IEC 989911990, Programming languages - C.
ISO/IEC TR 9973: 1988, Information processing - Procedures for registration of graphical items.
---------------------- Page: 8 ----------------------
GKS=3D/C ISO/IEC 8806-4 : 1991(E)
3 The C Language Binding of GKS-3D
The C language binding of GKS-3D shall be as described in clauses 3,4,5 and 6.
3.1 Conformance
This part of ISO/IEC 8806 incorporates the rules of conformance defined in the GKS-3D Standard (ISO
8805) for GKS-3D implernentations, with those additional requirements specifically def%red for C bindings
in GKS-3D.
The following criteria shall determine conformance of an implementation to this part of ISO/IEC 8806:
In Order to conform, an implementation sf the C binding of GKS-3D shall implement a specific level of
GKS-3D as spectied in ISO 8805. It shall make visible all of the declarations in the C binding spectied
in this part of ISO/IEC 8806 for that same level of GKS-3D and all lower levels and for a specific level
of c.
Thus, for example, the Syntax 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 ZlSmmy of characters terminated by the null Character (i.e.
. This means that the null Character is not usable as a printable Character.
‘\O’)
3.4 Function Identifiers
The function names of GKS-3D arc all mapped to C functions which begin with the letter g. Wo& and
phrases used in the GKS-3D function names arc often abbreviated in the representation and arc always
separated with the underscore Character WV Y The set of such abbreviations is given in 4.2, and the result-
ing C function names arc listed in 4.3. For example, the abbreviation for the GKS-3D function DELETE
SEGMENT FROM WORKSTATION is gdel seg WS.
del, seg, and WS arc abbreviations for
DELETE, SEGMENT, and WORKSTATION. Se co$inctive FROM is mapped to the null string.
The C Standard (ISO/IEC 9899) requires that Compilers recognize intemal identifiers which arc distinct in
at least 3 1 characters. That Standard also requires that extemal 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 intemal identifiers would be equivalent,
if they were both extemal identifiers, shall include a set of #def 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 extemal definitions may be found in annex D.
3.5 Registration
i tems
ISO 8805 reserves certain value ranges for registration’ as graphical items. The registered graphical
will be bound to the C programming language (and other programming languages). The registerec Il item
according to the rules for the designation and Operation of registration
IEC councils have designated the National Institute of Standards and
Yechnology), A-266 Technology Building, Gaithersburg, MD 20899,
---------------------- Page: 9 ----------------------
ISO/IEC 8806-4 : 199l(E) GKS=3D/C
Registration The C Language Binding of GKS-3D
binding will be consistent with the binding presented in this part of ISO/IEC 8806.
3.6 Identifiers for Graphical Items
Generalized Drawing Primitives and Escape functions arc referenced via identifiers. This part of ISO/IEC
8806 specifies the formst of the identifiers but it does not specify the registration of the identifiers. The
identifiers arc used as arguments to the functions ggdp, ggdp3, 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 GDP identifiers is:
/* 'nf is the registered GDP id. */
#define GGDP Rn n
( )
#define GGDP? Rn n /* 'nf is the registered GDP3 id. */
( 1
The format for unregistered GDP identifiers is:
#define GGDP Un (-n) /* 'nf is implementation dependent */
#define GGDP? Un (-n) /* 'nf is the registered GDP3 id. */
The format for registered%scape function identifiers is:
#define GESCAPE Rn (n) /* 'nf is the registered Escape id. */
The format for UnregisteredEscape function identifiers is:
(-n) /* 'nf is implementation dependent */
#define GESCAPE Un
-
3.7 Return Values
All GKS-3D/C functions retum void.
3.8 Header Files
C provides a mechanism to allow extemal ties to he included in a compilation. Clause 5 of this part of
ISO/lEC 8806 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-3D via the C binding.
This part of ISO/IEC 8806 uses the data type size t (as a field in the data type Gdata). The type
-
size t is environment-dependent (e.g. int, long int, unsigned int) and is defined in the file
. Therefore the file gks . h shall also include the file Xstddef . h>.
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 fle gks . h shal.l also contain extemal declarations for all GKS-3D/C functions because they retum
void. For example, the declaration for the function gopen gks would look like this:
-
extern void *err file, size t mem units);
gopen gks(char
- - - -
3.9 Memory Management
The application shall allocate the memory needed for the data retumed 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 retum 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 retums a simple, homogeneous, list of items.
For example, the function INQUIRE SET OF SEGMENT NAMES retums a list of the Segment names in
use. The other class retums complex, heterogeneous data structures. For example, the function INQUIRE
LOCATOR DEVICE STATE retums the device state which includes a locator data record; the data record
tan contain arbitrarily complex implementation-defined data structures. 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.
4
---------------------- Page: 10 ----------------------
GKS=3D/C ISO/IEC 8806-4 : 199l(E)
The C Language Binding of GKS-3D Memory Management
3.9.1 Functions which Return Simple Lists
Inquiry functions which retum a list of items arc bound such that the application tan inquire about a por-
tion of the list. This list is a subset of the implementation’s intemal list and is called the application’s list.
This alIows the application to process the implementation’s list in a piecewise manner rather than all at
once.
The application allocates the memory for a list and iasses that list to the implementation. The implementa-
P
tion places the results of the inquiry into the list. 1 ‘n Order to support this policy of mem ory management,
three additional Parameters have been added to functions which retum lists:
nun elems appl Xst: An integer input Parameter which is the length of the application’s list.
a)
The yalue of Y&m Zems appl list indicates the number of items (i.e. list elements) which will
fit into the applicat& list. Ä valueof 0 is valid and allows the application to determine the size of the
implementation’s list (which is retumed via num.elems-impl-list) without having the imple-
mentation retum any of the elements of its List.
If nun elems appl list is negative,
GE APPL LIST LENGTH LT ZERO is retumed as the value ofthe erro;indicaGr Parameter.
-
- - - e
Start ind: An integer input Parameter which is an index into the implementation’s list. (Index 0 is
b)
the firstelement 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 0 of the application’s list. Items arc copied
sequentially fiom the implementation’s list into the application’s list until the application’s list is full or
there arc no more items in the implementation’s list. If Start ind is out of range, error
GE START IND INVAL is retumed as the value of the error indicator&rameter.
-
- -
nun elems impl list: An output Parameter which is a pointer to an integer. The implementation
C)
- - -
stores into this Parameter the number of items that arc in the implementation’s list.
In annex possible underlying mechanism is described.
E, a
3.9.2 Functions which Return Complex Data Structures
The data retumed by the ESCAPE function and the functions which retum input device data records or pat-
tem tables tan 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 Stare, to
manage the memory for these functions.
The Stare resource is opaque to the application. The application does not know the structure of the Stare or
how it is implemented. The Stare is defined as a void * . This part of ISO/IEC 8806 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 Stare is used by the implementation to manage the memory needed by the functions which retum com-
plex data structures. Without specifying an implementation of a Stare, it is Safe to say that it will contain
and control memory needed to hold the data retumed by these functions and also co
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.