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

Status
Published
Publication Date
17-Dec-1991
Current Stage
9093 - International Standard confirmed
Start Date
23-Jan-2006
Completion Date
05-Apr-2022
Ref Project

Buy Standard

Standard
ISO/IEC 8806-4:1991 - Information technology -- Computer graphics -- Graphical Kernel System for Three Dimensions (GKS-3D) language bindings
English language
264 pages
sale 15% off
Preview
sale 15% off
Preview

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:
Technologies de I’information -. Infographie - Interfaces de langages
pour GKS (Graphical Kerne1 System) pow trois dimensions -
Partie 4: C
----
---pmwrz .__._.___-..-__ -.-.,----,----.
-- --
- --- .--
-- ---
---
-- _-
- Z
= =
= 5
Z -1 i
5 =
E =
Reference number
= =
C C
-- --
- ---- ----- _
---- --.- - ---. - ---------- - .____ ISO/1 EC 8806-4: 199 1 (E)
___ ____ -_ -_-_ --_- 4fzf- -.-.-... --.
---------------------- Page: 1 ----------------------
ISO/IEC8806=4:199l(E)
Contents

scope ........................................................................................................................................................

2 Normative references ...............................................................................................................................

. . . . . . . . . . . . . ..t.....................................................................................

3 The C Language Binding of GKS-3D

3.1 Conformance ...............................................................................................................................

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

3.2 Functions versus Macros

3.3 Character Strings .........................................................................................................................

3.4 Function Identifiers ......................................................................................................................

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

3.6 Identifiers for Graphical Items .....................................................................................................

3.7 Return Values ..............................................................................................................................

3.8 Header Files .................................................................................................................................

3.9 Memory Management ..................................................................................................................

3.9.1 Functions which Return Simple Lists ..............................................................................

........................................................ 5
3.9.2 Functions which Return Complex Data Structures

Error Handling .............................................................................................................................

3.10

3.10.1 Application Supplied Error Handlers ..............................................................................

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

3.10.2 Error Codes

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

3.10.3 C-specific GKS-3D errors

3.11 Colour Representations ................................................................................................................

.......................................................................................... 8

3.12 Storage of Multi-dimensional Arrays

3.12.1 Storage of 2*3 Matrices ...................................................................................................

3.12.2 Storage of 3*4 Matrices ...................................................................................................

3.12.3 Storage of 4*4 Matrices ...................................................................................................

3.12.4 Storage of Colour Arrays .................................................................................................

Tables ......................................................................................................................................................

...................................................................... 9
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-3D Name
..........................................
4.3.3 List Ordered Alphabetically by Bound Name within Level

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

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

Macro Definitions ..................................................................................................................................

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

6.2 Error Codes ................................................................................................................................

6.3 Miscellaneous Macros ...............................................................................................................

6.3.1 Linetypes ........................................................................................................................

6.3.2 Marker Types .................................................................................................................

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

6.3.3 Colour Models

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

6.3.4 Prompt and Echo Types

................................................................................ 76

6.3.5 Default Parameters of OPEN GKS

7 C GKS-3D Function Interface ...............................................................................................................

7.1 Notational Conventions .............................................................................................................

7.2 Control Functions ......................................................................................................................

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

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.
---------------------- 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-

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.

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

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

- - -

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.