ISO/IEC 8651-4:1995

INTERNATIONAL ISO/IEC
STANDARD 8651-4
Second edition
1995-06-01
Information technology - Computer
graphics - Graphical Kerne1 System (GKS)
language bindings -
Part 4:
C
Technologies de I ’information - Infogt-aphie - Interfaces langage avec
GKS -
Partie 4: C
Contents
V
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vi
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
ii
--
ISO/IEC 8651-4 : 1995(E)
0 ISO/IEC
6.2 Error Codes . . . . . . . . . . . . . . . . . . ‘.
6.3 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . “.
6.3.1 Linetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.2 Marker types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . “.
6.3.3 Hatch styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.4 Colour models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.5 Prompt and echo types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.6 Default Parameter of gopen gks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-
7 C GKS function interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notational conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1
Workstation independent functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2
7.2.1 Control functions .
7.2.2 Output functions .
7.2.3 Design output functions .
7.2.4 Primitive attribute functions .
7.2.5 Normalization transformation functions .
NDC picture functions .
7.2.6
7.2.7 Metafile functions .
7.2.8 Picture part store functions .
7.2.9 Input functions .
7.2.10 Font and glyph functions . 131
7.2.11 Audit and playback functions .
7.2.12 Inquiry functions .
7.2.13 Utility functions .
7.3 Workstation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.1 Control functions Y.
7.3.2 Inquiry functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.3 Retrieval functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.4 Viewing Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.5 Colour Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.4 Segment functions and workstation activation functions
7.4.1 Segment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.2 Workstation activation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.3 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
I
Annexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
A Compiled GKS /C specification .
AS Data types in compilation Order .
A.2 Macros .
A.3 Function calls .
A.4 Compatibility layer .
..............................................................................................................................
B Sample programs
B.l STAR .
B.2 IRON .
.................................................................................................................
c Short function identifiers
In Order of appearance .
c.1
............................................................................................................ 287
c.2 In alphabetical Order
......................................................................................................................
D Memory management
...........................................................................................................................
D.l Introduction
.......................................................................................
D.2 Functions that return simple lists
............................................................ 295
D.2.1 Operationof ginq_list line inds
................................................................................ -
D.3 Functions that return structured dZa
Operationof gcreate store .
D.3.1
. . .
0 ISOIIEC
ISO/IEC 8651-4 : 1995(E)
................................... 300
D.3.2 Operationof gincstroke-st and ginggat-rep
store .
D.3.3 Operation of gdel
..............................................................
E Compatibility with the 1991 editionof ISO/IEC 86514
edition . 307
E.l Comparison of this edition of ISO/IEC 86514 with the 1991
...............................................................
E.1.1 Changes in ISO/IEC 86514 data types
................................................................
E.1.2 Changes in ISO/IEC 86514 functions
........................................................................................................
E.2 The compatibility layer
................................................................................................
E.3 Theheader gks compat.h
-
............................................................................................
E.4 Datatypesin gks compat.h
-
.............................................................................................
E.4.1 Renamed data types
..............................................................................
E.4.2 Renamed fields of data types
...............................................................................................
E.4.3 Obsolete data types
E.5 Macros .
...................................................................................
E.6 Functions in the compatibility layer
Replaced functions .
E.6.1
Obsolete functions .
E.6.2
......................................................................................................................................
F Function lists
.....................................................................................................
F.l Alphabetic by GKS name
...............................................................................................
F.2 Alphabetic by binding name
iV
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.

ISO/IEC 8651-4: 1995(E) 0 ISO/IEC
Introduction
The Graphical Kerne1 System (GKS) functional description is registered as ISO/IEC 7942-1:1994. As
explained in the Scope and Field of Application of ISO/IEC 7942-1, that International Standard is
specified in a language independent manner and needs to be embedded in language dependent layers
(language bindings) for use with particular programming languages.
The purpose of this part of ISO/IEC 8651 is to define a Standard binding for the C Computer programming
language.
Vl
INTERNATIONAL STANDARD 0 ISO/IEC ISO/IEC 8651-4:1995(E)
Information technology - Computer graphics -
Graphical Kerne1 System (GKS) language bindings -
Part 4:
C
1 Scope
The Graphical Kerne1 System (GKS), ISO/IEC 7942-1: 1994 , specifies a language independent nucleus of
a graphics System. For integration into a programming language, GKS is embedded in a language depen-
dent layer obeying the particular conventions of that language. This part of ISOLIEC 8651 specifies such a
language dependent layer for the C language.

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.
I
--
0 ISO/IEC
ISO/IEC 8651-4 : 1995(E)
3 The C language binding
The C language binding of GKS shall be as described in clauses 3 to 7.
3.1 Classification and designation
This part of ISO/IEC 8651 incorporates the rules of conformance defined in the GKS Standard (ISO/IEC
7942-1) for GKS implernentations, with those additional requirements specifically defined for C bindings in
GKS.
The following criteria shall determine conformance of an implementation to this part of ISO/IEC 8651:
In Order to conform, an implementation of the C binding of GKS shall implement GKS as specified in
ISO/IEC 7942-1. It shall make visible all of the declarations in the C binding specified in this part of
ISO/IEC 8651 for a specific level of C.
Thus, for example, the sy ntax of the function names shall be precisely as specified in the binding and
Parameters shall be of the data types stated in the binding.
3.2 Functions versus macros
An implementation may Substitute macros for functions. However, the macros shall be designed so that
side-effects work properly. In general, a macro cannot be used to replace the error handling function
gerr hand. See also 3.10.
-
3.3 Character strings
The C language represents Character strings as an array of characters terminated by the null Character (i.e.
’ \ 0 ’ ). This means that the null Character is not usable as a printable Character.
3.4 Function identifiers
The function names of GKS are all mapped to C functions which begin with the letter g. Words and
phrases used in the GKS function names are often abbreviated in the representation and are always
separated with the underscore Character ll-ll. The set of such abbreviations is given in 4.2, and the result-
ing C function names are listed in 4.3. For example, the abbreviation for the GKS function DELETE SEG-
MENT FROM WORKSTATION is gdel seg WS. del, seg, and WS are abbreviations for
- -
DELETE, SEGMENT, and WORKSTATION. The conjunctive FROM is mapped to the null string.
The C language (ISO/IEC 9899) requires that Compilers recognize internal identifiers which are distinct in
at least 31 characters. That Standard also requires that external identifiers (i.e. those seen by the linker) be
recognized to a minimum of six characters, independent of case.
Implernentations which run in environments where two distinct C internal identifiers would be equivalent,
if they were both external identifiers, shall include a set of Object-like macros in the header which equate
the long names to a set of short names. A possible set of short names for a Compiler that accepts only 8
characters for external definitions may be found in annex C.
3.5 Registration
ISO/IEC 7942 reserves certain value ranges for registration’ as graphical items. The registered graphical
items will be bound to the C programming language (and other programming languages). The registered
item binding will be consistent with the binding presented in this part of ISO/IEC 8651.
’ For the purpose of this part of ISO/IEC 8651 and according to the rules for the designation and Operation of registration
authorities in the ISO/IEC Directives, the ISO/IEC council has designated the National Institute of Standards and Technol-
ogy (Institute of Computer Sciences and Technology), A-266 Technology Building, Gaithersburg, MD 20899, USA to act
as registration authority.
0 ISO/IEC
ISO/IEC 8651-4 : 1995(E)
3.6 Identifiers for graphical items
Generalized Drawing Primitives and Escape functions are referenced via identifiers. This part of ISO/IEC
8651 specifies the format of the identifiers but it does not specify the registration of the identifiers. The
identifiers are used as arguments to the functions ggdp and gescape.
An implementation may also represent GDPs and Escapes as separate functions, but this is not required.
There arc two formats for these identifiers. One format is for registered GDPs and Escapes and the other
format is for unregistered GDPs and Escapes.
The format for registered @DP identifiers is:
#def ine GGDP-Rn /* where 9P is the registered GDP
W
identifier */
The format for unregistered GDP identifiers is:
#define GGDP-Un d* where lnf is implementation
t-n)
dependent */
The format for registered Escape function identifiers is:
#def ine GESCAPE-Rn where %' is the registered
(n) /*
Escape identifier */
The format for unregistered Escape function identifiers is:
#define GESCAPEJJn (On) where In' is implementation
/*
dependent *%
3.7 Return values
All GMWC functions have return value void.
3.8 Headers
3.8.1 gks. h
C provides a mechanism to access information stored in a header via the #include preprocessing direc-
tive. Clause 5 of this part of ISO/IEC 8651 describes the data types that shall be defined in the header
gks . h which shall be included in any application program that intends to use GKS via the C binding.
This part of ISO/IEC 8651 uses the data type size t (inter alia as a field in the data type Gdata). The
-
type size-t is environment-defined (i.e. unsigned long or unsigned int) andisdefinedinthe
headers , , , , .
Additional implementation-dependent items may be placed in this header if needed. These items should
Start with the sentinel “G” or “g ”, as far as applicable.
The header gks . h shall also contain external declarations for all GKS/C functions because they have a
void return type. For example, the declaration for the function gopen-gks would look like this:
extern void
gopen-gks(const char *err-file, size-t memory);
3.8.2 gks
compat.h
-
For application programs which used to run on top of the 1991 edition of this part of HSO/IEC, the header
gks-compat . h is provided. gks-compat . h includes GKS/C data types that are no longer supported,
as well as external declarations for all GIWC functions that are no longer supported. Implernentations of
this part sf ISO/IEC 8651 shall support these functions in a compatibility layer, according to the guidelines
in Annex G of ISO/IEC 7942-1: 1994.
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 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 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) num~elems~appl~list: An integer input Parameter which is the length of the application ’s list.
The value of num elems appl list indicates the number of items (i.e. list elements) which will
fit into the applicatzn list. Ä valueif 0 is valid and allows the application to determine the size of the
implementation ’s list (which is returned via num~elems~impl~list) without having the imple-
mentation return any of the elements of its list. If num elems appl list is negative,
- -
-
GEAPPL-LIST-LENGTH-LT-ZERO is returned as the value of the error indicator Parameter.
b) Start ind: An integer input Parameter which is an index into the implementation ’s list. (Index 0 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 0 of the application ’s list. Items are copied
sequentially 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.
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 are in the impl ementation ’s list.
In annex D, a possible underlying mechanism is described.
3.9.2 Functions which return complex data structures
The data returned by inter alia the ESCAPE function, the AWAIT INPUT function and the functions which
return state lists or description 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 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 Stare.
-
A Stare 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 Stare, it
is safe to say that it will contain
ISO/IEC 8651-4 : 1995(E)
0 ISO/IEC
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 Stare 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 deallocates
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 Stare 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 Stare
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 S tore is deleted by the DELETE
STORE function or until the Store is used as an argument to a subsequent function, which returns complex
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 only contains the results of the last function.
This part of ISO/IEC 865 1 defines two errors that tan occur when using or creating a S tore; these errors are
described in 6.2. For most functions using a Store, these and other errors are returned via the “error indica-
tor-” Parameter. However, the function ESCAPE does not have an error indicator Parameter. For this func-
tion, the error reporting mechanism is used when an error is encountered. For this function, the implemen-
tation 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 definitions for the functions CREATE STORE and DELETE STORE follow:
CREATE STORE
Parameters:
out error indicator 1
out store STORE
Effect: Creates a Store and returns a handle to it in the output Parameter store. If the Store cannot
be created, the error indicator is set to one of the following error values:
GE-GM-NOT-OPEN GKS not in proper state;
GKS shall be in the state (GKOP, “)
GE-ERR-ALLOC-STORE Error while allocating Store
Errors: None.
DELETE STORE
Parameters:
out error indicator 1
out store
STORE
Effect: Deletes the Store and all internal resources associated with it. If there is not an error, the
Parameter store will be set to NULL to signify that it is no longer valid. If an error is detected,
the error indiocator is set to one of the following values:
GE-GM-NOT-OPEN GKS not in proper state;
GKS shall be in the state (GKOP, “>
Errors: None.
In 7.2.13.2, the C specification of these functions is given. In annex D, a possible underlying mechanism is
0 ISO/IEC ISO/IEC 8651-4 : 1995(E)
illustrated.
3.10 Error handling
3.10.1 Application supplied error handlers
User-defined error handlers shall accept the same arguments as the Standard error handler. The user-
defined error handler is specified by the Utility function (see also 7.2.13.2)
SET ERROR HANDLER
Parameters.
In New error handling function Function
Out Old error handling function Function
Effect: Sets the GKS error handling function to New eyyoy handlingfunction and returns the current
error handling function to Old error handling function.
Errors: None.
Application defined error handling functions accept the Same arguments as the Standard error handler. They
may invoke the Standard error logging function ERROR LOGGING.
ISO/IEC 7942 defines the initial error handling function to be ERROR HANDLING, that is, the value of
the Parameter Old error handling function Points to ERROR HANDLING, when SET ERROR HANDLER
is called for the first time.
When the application changes the error handling function, the implementation will invoke the new function
when an error is detected. If the application calls the default error handling function ERROR HANDLING,
ERROR HANDLING will always cal1 the function ERROR LOGGING.
If New error handler is not a valid pointer, the error handling will automatically be done by the Standard
error handler ERROR HANDLING.
User-defined error handlers may invoke the Standard error logging function ERROR LOGGING.
3.10.2 Error Codes
Hard coding numbers into a program decreases its maintainability. Therefore, this part of ISO/IEC 8651
defines a set of constants for the GKS error numbers. Esch error constant begins with the characters GE
--
See also 6.2 for the error macros.
3.10.3 C-specific GKS errors
This part of ISO/IEC 8651 defines some additional error messages. In 6.2 the numbers and their macros
are given.
3.11 Colour representations and specifications
GKS defines 4 colour models (RGB, CIE L*u*v* 1976, HLS and HSV) of which RGB and CIE L*u*v*
are mandatory. For each of these models, a colour specification is defined ( Grgb, Gcieluv, Ghsv,
Ghls ). The colour representation and specification are defined in 5.4 by the types Gcolr-rep and
Gcolr-specif.
3.12 Colour characteristics
GKS defines the colour characteristics as a basic type. The colour characteristics is defined in this part of
ISO/IEC 8651 by the data type Gcolr chars, which is documented in 5.3.
-
0 ISO/IEC
ISO/IEC 8651-4 : 1995(E)
3.13 Storage of multi-dimensional arrays
3.13.1 Storage of 2*3 matrices
The entries of Gtran matrix data types shall be stored such that the Segment transformation is defined
-
bY
mat[OJ];
Tp.x = mat[0,O]*p.x + mat[O,~]*p.y +
mat[l,O]*p.x + mat[l,l]*poy + -t[L21;
W*Y =
where p is a 2D Point, !l?p its transformation and mat is of eype Gtran-matrix.
3.13.2 Storage of conics in 3*3 matrices
The entries of Gconicmatrix data types shall be stored such that the conic is defined by
a[0,0]x2 + (a[O,l] + a[l,O]) xy + a[1,1]y2
+ (a[0,2] + a[2,0])x + (a[ 1,2] * a[2, l])y -+- a[2,2] = 0
where a isoftype Gconicmatrix.
3.13.3 Storage of colour arrays
The entries of Gpat rep data types shall be stored such that the colour specifier at the (i,j)-th entry is
-
given by
colr-rect.dir-colr.xxx[i + DX*j];i = O,.,DX-1; j
XXXi,j =
colr-rect.colr-array[i + DX*j];
colr-indij =
colr-rect.dims.size-x;
DX =
colr-rect.dims.sizey;
DY =
where xxx = (rgblcieluvlhlslhsv) is of type Gxxx and colr-rect is of type Gpat-rep.
3.14 Compatibility with the 1991 edition
In the second (1994) edition of ISO/IEC 7942 some functions and data iypes of ahe 1985 edieion have been
overtaken or deprecated. They are documented in the informative annex G. Examples are the GKSM func-
tions, which have been overtaken by AUDIT functions.
In this edition of ISO/IEC 8651-4 all functions and all data types of of the 1991 edition (the C binding of
the 1985 edition of ISO/IEC 7942) have been preserved. The support of overtaken or deprecated functions
or data types falls into two categories:
1) Functions which have been renamed (e.g. INQUIRE TEXT EXTENT -+ GET TEXT EXTENTJ or
which have been incorporated into more compact functions (e.g. the OUTPUT functions).
These functions and their related data types are documented in clauses 5 and 7. For example,
the function CREATE OUTPUT PRIMITIVE has been bound to the C function
gcreate-outgrim. Besides that, however, the output functions gpolyline,
gpolyline set, gnurb-set, geonie-sec-Set, gpolymarker. gfill-area,
-
gfill-area-set, gell-sec-Set, gell-seg-set, gell-disc-Set,
gclosed-nurb-set, gtext, geell-array, gdesign, ggdp havebeendefined.
2)
Functions which have been deprecated (INQLHXE GKS LEVEL) or which have been overtaken by other
functions (GKSM functions, for example) .
These functions are documented in annex E. They will be deleted at the next edition of ihis part of
ISO/IEC 865 1.
--
0 ISO/IEC
4 Tables
4.1 Abbreviation policy in construction of identifiers
In the construction of the several data types, function names, etc., the following policy is applied:
1) All identifiers in the C binding are abbreviated using the same abbreviations for every component and
using underscores to denote blanks.
2) The Plural of an expression is constructed by adding an “s” after its abbreviation; so, for example, “vec-
tor” is abbreviated to “vec” and “vectors” is abbreviated to “vecs ”; if an expression is mapped to NULL,
so will be its Plural.
3) Digits are also preceded by underscores.
4) The word REALIZED is not abbreviated in the second field of the enumeration data type
Ginq_type; in all other cases it is abbreviated using the list in 4.2.
5) Construction of GKS/C identifiers:
Function names:
a)
“g” (lower case) followed by abbreviated function name in lower case;
Data types:
b)
“G” (upper case) followed by abbreviated data type in lower case;
“redundant” (words in the field name that
Fields of data types; the following refinements are used:
(9
are identical to those in the structure name) Parts are omitted, if the context allows this; thus the
linewidth in the field of Gline bundle is abbreviated to width, because the context makes
-
clear which width is used;
Function macros:
"Gfn ” followed by abbreviation of function name;
Error macros:
e>
"GE ” followed by some abbreviated expression;
-
Fields of enumeration types:
“G” (upper case) followed by a prefix followed by an abbreviation of the field name; this prefix is
constant for each enumeration field; all the fields are in upper case.
4.2 Table of abbreviations used
In this table, only words which are abbreviated are listed. They are used for
function names;
data types;
fields of data types;
error macros.
The word “NULL” denotes those words which are deleted completely when forming function names or
data types.
Abbreviation
Word or Phrase
cieluv
CIE L*u*v* (colour model)
accum
accumulate
act
actual
add
addition
align
alignment
alloc
allocate
NULL
and
ISO/IEC 8651-4 : 1995(E)
0 ISOIIEC
application
aPP1
arithmetic
arith
associate(d)
assoc
at
NULL
attribute
attr
attribute Source flag
asf
availability
avail
available
avail
begin
heg
between
NULL
boundaries
bndries
boundary
bndry
buffer
buf
cannot
cant
centre
ctr
Character
char
characteristics
chars
circular
circ
classification
class
clipping
Clip
colour
colr
component
comp
composite
comp
composition
comp
concatenation
concat
connection
contour
cont
control
ctrl
conversion
conv
coordinate
coord
correspondence
corr
criterion
crit
current
cur
dashed
dash
default
def
defined
def
delete
del
deletion
del
dependent
dep
description table
dt
designation design
detectability
det
detectable det
device dev
device coordinate(s) dc
digital digit
dimension dim
direction dir
display disp
dotted dot
duplicate
dup
elliptic ell
--
ISO/IEC 8651-4 : 1995(E)
0 ISO/IEC
equal eq
err
error
evaluate
expan
expansion
fac
facility
NULL
factor
fill
fill area
NULL
from
func
function
generalized drawing primitive gdp
generic
gen
gkcl
gks closed
gks open gkop
graphical graph
hand
handling
ht
height
high1
highlighted
high1
highlighting
homo
homogeneous
hor
horizontal
hls
hue lightness Saturation (colour model)
hsv
hue Saturation value (colour model)
hyperbola hYP
id
identifier
impl
implernantation
impl
impl icit
NULL
in
NULL
in use
ind
index
ind
indicator
ind
...