1、INTERNATIONAL STANDARD ISO/IEC 8651-4 Second edition 1995-06-01 Information technology - Computer graphics - Graphical Kernel System (GKS) language bindings - Part 4: C Technologies de /information - lnfographie - Interfaces langage avec GKS - Partie 4: C Reference number ISO/IEC 8651-4:1995(E) ISO/
2、IEC 8651-4:1995(E) Contents Foreword v Introduction vi 1 Scope . 1 2 Normative references . 2 3 The C language binding .3 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 Classification and designation . .3 Functions versus macros 3 Character strings .3 Function identifiers .3 Registrati
3、on 3 Identifiers for graphical items .4 Return values . 4 Headers 4 3.8.1 gks . h . . 3.8.2 gks-c0mpat.h . 4 Memory management 5 3.9.1 Functions which return simple lists .5 3.9.2 Functions which return complex data structures .5 Error handling . 7 3.10.1 Application supplied error handlers . .7 3.1
4、0.2 Error codes .7 3.10.3 C-specific GKS errors .7 Colour representations and specifications . .7 Colour characteristics .7 Storage of multi-dimensional arrays . .8 3.13.1 Storage of 2*3 matrices .8 3.13.2 Storage of tonics in 3*3 matrices .8 3.13.3 Storage of colour arrays .8 Compatibility with the
5、 1991 edition .8 4 Tables Y 4.1 Abbreviation policy in construction of identifiers .9 4.2 Table of abbreviations used .9 4.3 Function names .13 4.3.1 List ordered alphabetically by bound name . 13 4.3.2 List ordered alphabetically by GKS name . 20 5 Type definitions . 28 5.1 Mapping of GKS data type
6、s . .28 5.2 Environment-defined type definitions .28 5.3 Implementation dependent type definitions .29 5.4 Implementation independent type definitions .35 6 Macro definitions 91 6.1 Function identifiers . 91 6.1.1 In order of appearance . 91 6.1.2 In alphabetical order .95 0 ISO/IEC 1995 All rights
7、reserved. Unless otherwise specified, 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. ISO/IEC Copyright Office l Case postale 56 l CH-1211 Genkve 2
8、0 l Switzerland Printed in Switzerland ii 0 ISO/IEC ISO/IEC8651-4:1995(E) 6.2 Error codes . 99 6.3 Miscellaneous 104 6.3.1 Linetypes . ,104 6.3.2 Marker types . .104 6.3.3 Hatch styles . .104 6.3.4 Colour models .104 6.3.5 Prompt and echo types . .105 6.3.6 Default parameter of gopen-gks 105 7 C GKS
9、 function interface .106 7.1 Notational conventions . .106 7.2 Workstation independent functions .106 7.2.1 Control functions . .106 7.2.2 Output functions .108 7.2.3 Design output functions . .llO 7.2.4 Primitive attribute functions .113 7.2.5 Normalization transformation functions . .119 7.2.6 NIX
10、 picture functions .120 7.2.7 Metafile functions .121 7.2.8 Picture part store functions .I22 7.2.9 Input functions . .124 7.2.10 Font and glyph functions . 131 7.2.11 Audit and playback functions . .131 7.2.12 Inquiry functions .132 7.2.13 Utility functions . .145 7.3 Workstation functions 148 7.3.
11、1 Control functions . .148 7.3.2 Inquiry functions .155 7.3.3 Retrieval functions 172 7.3.4 Viewing utility functions . 173 7.3.5 Colour utility functions . .173 7.4 Segment functions and workstation activation functions ,173 7.4.1 Segment functions .173 7.4.2 Workstation activation functions . 176
12、7.4.3 Utility functions . .176 Annexes 177 A Compiled GKS/C specification . .177 A.1 Data types in compilation order .177 A.2 Macros 223 A.3 Function calls ,231 A.4 Compatibility layer .260 B Sample programs 271 B.l STAR . 271 8.2 IRON. 273 C Short function identifiers .280 c.1 In order of appearanc
13、e .280 c.2 In alphabetical order . .287 D Memory management . .294 D.l Introduction . 294 D.2 Functions that return simple lists .294 D.2.1 Operation of ginelist-line-inds . .295 D.3 Functions that return structured data 297 D.3.1 Operation of gcreate_store.29 8 . . . 111 ISO/IEC8651-4:1995(E) 0 ISO
14、/IEC D.3.2 Operation of ging_stroke-st and ginggat_reg.30 0 D.3.3 Operation of gdel-store . .304 E Compatibility with the 1991 edition of ISO/IEC 86514 . .307 ES Comparison of this edition of ISO/IEC 86514 with the 1991 edition . .307 EA.1 Changes in ISO/IEC 86514 data types .307 E.1.2 Changes in IS
15、O/IEC 86514 functions . .308 E.2 The compatibility layer . .309 E.3 The header gks_compat.h30 9 E.4 Data types in gks-comgat .h 30 9 E.4.1 Renamed data types . 309 E.4.2 Renamed fields of data types . .309 E.4.3 Obsolete data types . 310 E.5 Macros 314 E.6 Functions in the compatibility layer .314 E
16、.6.1 Replaced functions 314 E.6.2 Obsolete functions 317 F Function lists 324 F.l Alphabetic by GKS name . 324 F.2 Alphabetic by binding name . 331 iv 0 ISO/IEC ISO/IEC 8651-4 : 1995(E) Foreword IS0 (the International Organization for Standardization) and IEC (the Inter- national Electrotechnical Co
17、mmission) form the specialized system for worldwide standardization. National bodies that are members of IS0 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.
18、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 technical committee,
19、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 8651-4 was prepared by
20、 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 I), which has been technically revised. ISO/IEC 8651-4 consists of the following parts, under
21、 the general title Information technology - Computer graphics - Graphical Kernel System (GKS) language bindings: - Part I: FORTRAN - Part 2: Pascal - Part 3: Ada - Part 4: C Annexes A to F of this part of ISO/IEC 865 1 are for information only. ISO/IEC 8651-4 : 1995(E) 0 ISO/IEC Introduction The Gra
22、phical Kernel System (GKS) functional description is registered as ISO/lEC 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 bind
23、ings) 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. INTERNATIONAL STANDARD 0 ISO/IEC ISO/IEC 8651-4:1995(E) Information technology - Computer graphics - Graphical Kernel System (GKS) la
24、nguage bindings - Part 4: C 1 Scope The Graphical Kernel 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
25、. This part of ISO/IEC 865 1 specifies such a language dependent layer for the C language. 1 ISO/IEC 8651-4 : 1995(E) 0 ISO,lEC 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
26、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 IS0 maintain r
27、egisters of currently valid International Standards. ISO/IEC 7942-1:1994, Information technology - Computer graphics and image processing - Graphical Kernel System (GKS) - Part 1 : Functional description. ISO/IEC 9899:1990, Programming languages - C. ISO/IEC TR 9973:1994, Information technology - Co
28、mputer graphics and image processing - Procedures for registration of graphical Items. 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 rule
29、s of conformance defined in the GKS Standard (ISO/IEC 7942-l) 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 865 1: In order to conform, an impleme
30、ntation of the C binding of GKS shall implement GKS as specified in ISO/IEC 7942-l. It shall make visible all of the declarations in the C binding specified in this part of ISO/IEC 865 1 for a specific level of C. Thus, for example, the syntax of the function names shall be precisely as specified in
31、 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
32、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 a
33、re 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 11-11. The set of such abbreviations is given in 4.2, and the result- ing C function names a
34、re 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 rec
35、ognize 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 internal i
36、dentifiers 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 an
37、nex 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
38、 of ISO/IEC 865 1. 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
39、and Technology), A-266 Technology Building, Gaithersburg, MD 20899. USA to act as registration authority. ISO/IEC 8651-4:1995(E) 0 ISO/IEC 3.6 Identifiers forgraphicalitems Generalized Drawing Primitives and Escape functions are referenced via identifiers. This part of ISO/IEC 8651 specifies the for
40、mat of the identifiers but it does not specify the registration of the identifiers. The identifiers are used as arguments to the functions ggdD and gescage. An implementation may also represent GDPs and Escapes as separate functions, but this is not required. There are two formats for these identifi
41、ers. 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 GGDPJn In) /* where nr is the registered GDP identifier */ The format for unregistered GDP identifiers is: #define GGDP-Un 1 -n) /* wher
42、e nr is implementation dependent */ The format for registered Escape function identifiers is: #define GESCAPE-Rn (n) /* where nr is the registered Escape identifier */ The format for unregistered Escape function identifiers is: #define GESCAPE-Un t-n) /* where nr is implementation dependent */ 3.7Re
43、tum values All GKS/C 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
44、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) and is defined in the headers , cstd
45、def.h, , , . 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 ex
46、ample, the declaration for the function gogen-gks would look like this: extern void gogen-gks(const char *err-file, size-t memory); 3.8.2 gks-c0mgat.h For application programs which used to run on top of the 1991 edition of this part of ISO/IEC, the header gks-cornpat . h is provided. gks-comgat . h
47、 includes GKS/C data types that are no longer supported, as well as external declarations for all GKS/C functions that are no longer supported. Implementations of this part of ISO/IEC 865 1 shall support these functions in a compatibility layer, according to the guidelines in Annex G of ISO/IEC 7942
48、-l : 1994. 0 ISO/IEC ISO/IEC 86514 : 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 i
49、nformation 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 lengt
