ISO/IEC 9638-3:1994

INTERNATIONAL lSO/lEC
STANDARD 9638-3
First edition
1994-l 2-15
Information technology - Computer
- Interfacing techniques for
graphics
dialogues with graphical devices (CGI) -
Language bindings -
Part 3:
Ada
Technologies de /‘information - lnfographie - Techniques in terfaciales
pour dialogues avec dispositifs graphiques (CGI) - Liants de langage -
Partie 3: Ada
Reference number
SO/I EC 9638-3: 1994(E)

---------------------- Page: 1 ----------------------
ISOAEC 9638-3: 1994(E)
Contents
iv
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
v
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction
1
1 scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*.
2Normativereferences. 2
3
.................................................................
3 Principles.
3
3.1Conforman~ .
3
3.2ImpIicationsofthelanguage .
3
...........................................
3.2.1FunctionaImapping.
................................ 5
32.2 Implementation and host dependencies
................................................. 5
3.2.3 Error handling
......................................... 7
3.2.4 Continuation of functions
8
3.2.5Packeddataformats. .
8
.....................................
3.2.6Eventsandeventreportlists.
9
...............................................
3.2.7DataInapping.
................................................. 11
3.2.8 Mu&i-tasking
11
3.2.9Packaging .
...................................... 13
3.2.10 Client program environment
................................................. 13
3.2.11Registration
14
4Tables .
14
................................
4.1AbbreviationsusedintheAdaIanguagebinding
................................ 14
4.2 Abbreviation policy in construction of identifiers
.................................................... 15
4.3 CGI function names
.......................................
15
43.1 Alphabetical byboundname
.................................. 21
4.3.2 Alphabetical by CGI function name
5 CGI configuration values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
34
..............................................................
6Typedeftitions
35
....................................................
6lArrayindexranging
....................................... 36
6.2 Representation of CGI basic data types
............................................. 42
6.3 Representation of CGI strings
......................................... 44
6.4RepresentationofCGIdatarecords
45
.....................................
6.5RepresentationofCGIabstractdatatypes
53
..................................
6.6RepresentationofCGIenumerateddatatypes
0 ISO/IEC 1994
All rights 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 CM-121 1 Geneve 20 l Switzerland
Printed in Switzerland
ii

---------------------- Page: 2 ----------------------
ISO/IEC 9638-3: 1994(E)
01s0/IEC
67
.................................................
6.7CGIAdammrdtypes.
77
6.8CGIAdasubtypes .
78
6e9CGIAdaarraytypes .
91
6.1OCGIAdaaccesstypes. .
...................................................... 92
6M CC1 exceptions
93
............................................................
7 CGVAda functions
93
................................................
7.1Part2controlfunctions.
................................................. 100
7.2 Part 3 output functions
7.3Part4segmentfunctions. . 125
130
7.4 Part 5 input functions .
.................................................. 155
7.5 Part 6 raster functions
160
7.6 Binding defmed utility functions .
168
............................................
7.6e1 Data record utiIities
7.6.1.1 Datarecord utility constants . 160
163
7.6.1.2Datamordutilitytypes .
164
7.6.1.3 Data record utility fhctions .
174
7.6.2 String utilities .
.................................. 174
7.6.2.1 String utility functions
........................................ 175
7.6.3ErrorhandIingutiIities.
............................. 175
7.6.3.1 Error handling utility functions
........................................... 177
7.6.4 Data packing utihties
................................ 177
7.6.4.1 Data packing utility types
............................. 178
7.6.4.2 Data packing utility functions
181
AnnexA .
....................................... 182
A.1 Package specification CGI CONFIG
187
A.2 Package specification CGI?IYPES
218
A.3PackagespecificationCGI-DATARECIIK;)’UTILS’:::::::::::::::::::::::::::
A.4PackagespecificationCGI~ . . . . . 225
A.5 Package specification CGI -PROFILE ID-CONST 271
273
A.6 Package specification CGIkJNCTI&N ID-CONST
295
A.7 Package specifkation CGIkGISTRA?ION-CONST .
297
A.8 Package specification CGI-ERROR CONST
A.9 Package specification CGI~STRING$TILS . 310
311
A.lOPackage specification CGI ERROR HANDLINGJJTILS
...................................................... 312
A.11 Package s&cificati~ CGI~PACtiGJI’ILS
315
AnnexB .
315
B.l Example Program 1: Star .
319
B.2 Example Program 2: Name Object .
328
B.3 Example Pmgram 3: Text .
331
B.4ExampleProgram4:LoacfCGIDatabase. .
335
B.4ExamplePmgram5:EventQueuePkg. .
AnnexC . . . . . . . . . . . . . . . 0. 340
AnnexD . . .-.*.- . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
AnnexE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .*“.~.~ . . . . . 354
. . .
111

---------------------- Page: 3 ----------------------
ISODEC 9638-3: 1994(E)
01s0/IEc
Foreword
IS0 (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 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.
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, 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 9638-3 was prepared by Joint Technical Com-
mittee ISO/IEC JTC 1, Information technology, Subcommittee 24, Computer
graphics and image processing.
ISO/IEC 9638 consists of the following parts, under the general title Information
technology - Computer graphics - InterjYacing techniques for dialogues with
graphical devices (CGI) - Language bindings:
- Part I: FORTRAN
- Part 2: PASCAL
- Part 3: Ada
Annexes A, B, C, D and E of this part of ISO/IEC 9638 are for information only.
iv

---------------------- Page: 4 ----------------------
ISOmc %38-3: 19!M(E)
01s0mc
Introduction
The Computer Graphics Ierhce (CGI) (ISMEC 9636) is specifaed in a Ianguage indepmknt manner and
nt35dstQbeemWinbguage t kqers (language bindings) fix= use with particular programmQ
languages.
The purpose of this document is to define a standard binding of CGI to the Ada computer paqpmming
lawwUF*
V

---------------------- Page: 5 ----------------------
This page intentionally left blank

---------------------- Page: 6 ----------------------
INTERNATIONAL STANDARD 0 ISO/IEC
ISO/IEC 9638-3: 1994(E)
- Computer graphics - Interfacing
Information technology
techniques for dialogues with graphical devices (CGI) -
Language bindings -
Part 3:
Ada
1 scope
The Computer Graphics Interface (CGI) (ISO/IEC 9636), specifies a language independent standard interface
between device-independent and device-dependent parts of a graphics system. For integration into a
programming language, CGI is embedded in a language dependent layer obeying the particular conventions of
that language. This part of ISO/IEC 9638 specifies such a language dependent layer for the Ada programming
mww*

---------------------- Page: 7 ----------------------
ISO/IEC 9638-3: 1994(E) OISCYIEC
2 Normative references
The following standards contain provisions which, through reference in this text, constitute provisions of this
part of ISO/IEC 9638. At the time of publication, the editions indicated were valid. All standards are subm
to revision, and parties to agreements based on this part of ISO/IEC 9638 are encmraged to investigate tie
possibility of applying the most recent editions of the standards listed below. Members of IEC and IS0
maintain registers of currently valid International Standards.
IS0 86521987, Programming Languages - Add
ISO/IEC 9636l:l!Wl, Inform&on technology - Computer graphics - Inte#iixing techniques for dialogues with
graphics devices (CGI) - Functional Specification - Part I: Overview, profiles, and conformance.
ISOIIEC %362:1991, Infonnution technobgy - Computer graphics - Interfacing techniques for dialogues with
graphics devices (CGI) - Functional Specification - Part 2: Control.
ISO/IEC 9636-3:1991, Inform&n techmlogy - Computer graphics - Interfking techniques for dialogues with
graphics devices (CGI) - Functional Specification - Part 3: Output.
ISO/IEC 96364: 1991, Information technology - Computer graphics - Megacing techniques for dialogues with
graphics devices (CGI) - Functional Specification - Part 4: Segments.
ISO/IEC 963&5:1991, Infomation technology - Computer graphics - InterjMng techniques for dialogues with
graphics devices (CG) - Functional Specification - Part 5: Input and echoing.
ISOIIEC 9636-6: 1991, Information technology - Computer graphics - Interlfacing techniques for dialogues with
graphics devices (CG) - Functional Specification - Part 6: Raster.
ISO/IEC 9637-1:1992, Information technology - Computer graphics - Interjking techniques for diulogues with
graphics devices(CGI) - Data stream binding - Part 1: Character encoding.
ISOIIEC 9637.211992, Information technology - Computer graphics - Imerfiacing techniques for dialogues with
graphics devices(CG) - Data stream binding - Part 2: Binary encoding.
Nonnative references
2

---------------------- Page: 8 ----------------------
ISO/IEC 9638-3: 1994@)
This binding wpports the implementation independent aspects of the Ada standard except as discussed under
multi-tasking. This binding does not assume that the compiler qports any Ada hguage features which are
im&zmentation dependent, but implies that the compiler must be able to support the declarations contained in
this CGI/Ada biig.
This binding does not make any assumptions regarding the machine representation of the predefmed Ada
numeric types.
3.1 ConfomuuKe
This binding incorporates the rules of conformance def@ in the ISO/EC 9636 for CGI implementations with
these additional requirements specifically defined for Ada implementations of CGI.
The following criteria are established for de&mining conformance or non-conformance of an implementation
to this binding:
- The semantics of an implementation shall be those stated in the CGI standard as modified or extended for
Ada as stated in this binding document.
- The package(s) corresponding to CGI shall be an available Ada library unit, with all names as specified by
this document or as modified fcx one or more CGI profiles.
3.2 Implications of the hqguage
3.2.1 Fundhad mapping
The functions whi& constitute the ISO/IEC 9636 are each mapped to Ada procedures within this language
binding. This mapping utilizes a one&one correlation between the CGI functions embodied in the CGI
standard and the A& pmcabes herein, with the exception of the generic functiomd defmitions within the CGI
standard In the case of these generic functional defmitions, multiple Ada procedures have been utilized to
attain the fimctiond mapping (binding). The following list denotes all such functions and their Ada binding
complements:
ISOLIEC 9636 Function : Put Current &put classy Measwe
isboundto-PutCutrentLocatorMeasure
Put Current Strcke Measure
Put C\preat Vahatm Measure
Put Current Choice Measure
Put Current Pick Measure
Put Current String Measure
Put Current Raster Measure
Put Current General Measure
ISO/IEC 9636 Function : 4nput class Device Data
Principles

---------------------- Page: 9 ----------------------
OISO/IEc -
ISO/IEC 9638-3: 1994(E)
is bound to - Set Locator Device Data
Set Stroke Device Data
Set Valuator Device Data
Set Choice Device Data
Set Pick Device Data
Set String Device Data
Set Raster Device Data
Set General Device Data
ISO/IEC 9636 Function : Request
is bound to - Request Locator
Request Stroke
Request Valuator
Request Choice
Request Pick
Request Suing
Request Raster
Request General
ISO/IEC 9636 Function : Sample
is bound to - Sample Locator
Sample Stroke
Sample Valuator
Sample Choice
Sample Pick
Sample String
Sample Raster
Sample General
ISO/IEC 9636 Function : Echo Request
is bound to - Echo Request Locator
Echo Request Stroke
Echo Request Valuator
Echo Request Choice
Echo Request Pick
Echo Request Suing
Echo Request Raster
Echo Request General
ISO/IEC 9636 Function : Dequeue Event
is bound to - Dequeue Locator Event
Dequeue Stroke Event
Dequeue Valuator Event
Dequeue Choice Event
Dequeue Pick Event
Dequeue Suing Event
Principles

---------------------- Page: 10 ----------------------
OISO/IEC ISOAEC 9638-3: 1994(E)
Dequeue Raster Event
Dequeue General Event
ISO/IEC 9636 Function : Update Echo Output
is bound to - Update Locator Echo Output
Update Stroke Echo Output
Update Valuator Echo Output
Update Choice Echo Output
Update Pick Echo Output
Update String Echo Output
Update Raster Echo Output
Update General Echo Output
3.2.2 Implementation and host dependencies
There are a number of implementation and host dependent issues which will be associated with an Ada
compiler and its run-time environment. These issues will affect the portability of application (client/generator,
driver, target, . .) programs utilizing this binding of CGI. The client programmer should follow accepted
practices for ensuring portability of Ada programs to avoid introducing problems when rehosting an application
of CGI to another system. This binding attempts to avoid dependencies on compiler specific Ada types which
may vary from machine to machine.
Since CGI provides for variable precisions which may be specified by the client, the situation could exist in
which an 8-b& 16-b&, 24bit, or 32.bit machine will meet all of the required needs for a particular CGI client
as long as the client stays within the ranges provided by the host machine. Wherever possible, universal
integer type definitions have been applied in this part of ISO/IEC 9638 in order to support the variable
precisions required by the CGI client. These universal types are specified via minimum and maximum values
which are contained in the CGI configuration package. Therefore a conforming implementation/application of
CGI may change these value range limits to meet its particular needs. Some additional range limits were
added in the CGI configuration package to handle the mapping of the Fixed Integer data type. Since the
ISO/lEZ 9636-l provides a fixed integer (IF’) data type which can either be a fixed 8, 16, or 32 bit integer, it
was decided to map each subtype of the fixed integer with its own range value limits. The fmed integer
definitions which were mapped in this way were the Device Coordinate, Error Report, Intrinsic Name, and
Input Surface Coordinate types. Through this mapping, the fmed integer type definitions may be changed
easily by the client at compile time of the CGI. For an implementation of CGI which generates a data stream,
it is possible that the precision specified at the language binding layer may differ from the precision specified
for data stream transmission. If a particular implementation or client application of CGI can not support all of
the fixed integer type definitions, the non-supported fixed integer definitions should be redefined or removed.
If such a situation occurs and a precision is selected by a client which the implementation can not support, the
CGI 3:204 error, specified precision requirement not achievable shall be logged to the error queue.
3.2.3 Error handling
CGI provides an error queue implementation which can be inquired about by a client. Through this
mechanism, CGI errors can be dequeued by the client and error handling controls can be put in effect by the
client. In certain configurations of CGI, this error handling mechanism will not be able to account for errors
which occur through the improper execution of this language binding. Cases like this include, but are not
limited to Generator/Interpreter implementations or any implementation where the language binding does not
co-exist with the graphics interpreter. For these situations an implementation of CGI may choose to define an
Principles 5

---------------------- Page: 11 ----------------------
ISO/IEC 9638-3: 1994(E) OISO/IEc
error handler in order to detect, record, and report errors which occur as a result of Ada language binding
violations. It is the intent of this language binding that all of the Ada predefmed exceptions (
ERROR, and
NUMEIW~E~OR, PItOGRAM ERROR, STORAGE ERROR, CONSTRAINT
TASKING ERROR ) be handled without causing interruption to client per&x-ma&e. This is in accordance
-
with the ISOEC 9636 error philosophy which states that the CGI does not automatically report errors to the
client program. Detection of any of these predefined Ada exceptions during the implementation’s execution of
a function, will result in the generation of the appropriate binding specific error (if allowed by the error
controls in effect).
This part of ISO/IEC 9638 defines an error handling scheme for the language binding which is implemented in
A language
much the same fashion as the interpreter error handling mechanism defined in the ISO/IEC 9636.
binding error queue and a set of error handling controls which are modifiable via the CGI function,
SET~ERRORJMNDLING~CONTROLS may be provided in order to give the client greater visibility into the
performance of the language binding implementation. This is knowledge which the client may find beneficial
either in integrating to or in determining the limitations of a CGI implementation or system. Any language
binding error functionality shall always default to the default states defined in the ISO/IEC %36 upon system
startup or upon the receipt of an INITIALIZE~SESSION command. While in the disabled state no binding
errors will be queued. All error reporting shall remain under client control. If such an error implementation is
An implementation of CGI may choose
provided by a language binding, it shall be explicitly documented.
whether or not to provide additional error detection facilities, but in either case shall provide the inquire error
handling support function in the error handling utilities package. Subclause 7.6 will contain more information on
the specific binding and implementation of the error functions.
It is also necessary for the Ada language binding to include a file of defined error constants for shared use
between the client and the language binding. This file will contain all of the CGI errors defined in the ISO/IEC
9636 (for client interpretation) as well as any implementation dependent errors which have been defined by the
client or the implementation (all negative). All implementation defined errors should be explicitly documented
by the CGI implementation. The language binding error constants file shall be called CG1 ERROR CONST and
- -
wi
shall be encoded as described in Annex A. The language binding error constants file so contain the
nding errors will be
predefined language binding errors defined in this standard. All predefined Ada languag
Ada language
of the appropriate CGI error class (according to the guidelines in the ISO/IEC 9636-l).
binding error identifiers defined within this part of ISO/IEC %38 will be numbered starting with error identifier
2500. The language binding specific errors listed in order of error class are
defined as follows:
Error Identifier: 3:2500
Cause: Content of Packed Data Array Invalid
Function ignored.
Reaction:
Error Identifier: 5:2500
Cause: Data Continuation Expected, Not Received
Reaction: Function ignored.
Error Identifier: 6:2500
Cause: Ada Constraint Error
Reaction: Function ignored.
6:2501
Error Identifier:
Ada Numeric Error
Cause:
Function ignored.
Reaction:
Principles
6

---------------------- Page: 12 ----------------------
ISO/IEC 9638-3: 1994(E)
OISO/IEC
Error Identifier: 62502
Cause: Ada Program Error
RMtion: Function ignored.
Error Identifier: 6:2503
Cause: Ada Storage Error
Reaction: Function ignored.
Error Identifier: 6:2504
Ada Tasking Error
Cause:
Reaction: Function ignored.
Error Identifier: 6:2505
Client Out of Memory
Cause:
Reaction: Function ignored.
3.2.4 Continuation of functions
Certain CGI functions have been bound such that the data associated with the single, conceptual CGI function
can be partitioned. In general these CGI functions handle data which may be of indeterminate length and may
be very large. The intent is to allow clients of the procedural binding to pass large quantities of data to a CGI
implementation without having to buffer all of the data at one time in the client’s memory.
The functions which have been bound in this manner are:
Cell Array
Generalized Drawing Primitive
Pixel Array
Polygon
Polyline
The
The continuation of these functions has been provided for through the addition of a continuation flag.
continuation flag will appear as the last input parameter in the function’s parameter list. The continuation
parameter is a FINALJLAG TYPE enumerated value and will indicate to an implementation the state of the
-
input data If the flag is set to FINAL, the input data passed in with the function is the last or only data
partition. If the flag is set to NOT FINAL, it is expected that the client will continue to call this function
providing input data partitions which are to be appended in secession until a call of the function is processed
with the continuation flag set to FINAL. After the first partition of a continuation function is received, each
successive call to the function shall only contain valid information for the portion of the function which is being
extended as follows:
Cell Colour Specifiers
Cell Array
Point List
Generalized Drawing Primitive
Colour Specifiers
Pixel Array
Point List
Polygon
Point List
Polyline
In this binding, the continuation flag shall be implemented as a defaulted parameter with a default value of
FINAL. With this parameter defaulted to FINAL, a client may execute any of the continuation functions without
specifying the value of the continuation flag and achieve the effect of the function exactly as it is described in
7
Principles

---------------------- Page: 13 ----------------------
ISO/IEC 9638-3: 1994(E) OISOLIEC
the ISO/IEC 9636. When a function is processed by an implementation with a value of NOT_FINAL, failure to
invoke the same function with further continuations or a final data partition will result in the class 5 binding
specific error, Data Continuation Expected, Not Received. The reaction to this error will be to ignore the
function causing the error. If the execution of a function causes an error while the continuation flag is set to a
value of NOT FINAL, the implementation must honour the state of the continuation flag and discontinue the
execution of the function. This means accepting data partitions for the function until a partition is received with
a continuation flag value of FINAL (even though further data partitions will have no effect). This is done in
order to preserve the client’s state of execution and to reduce side affects.
3.2.5 Packed daQa formats
The following CGI functions have been bound such that the data with the single, conceptual CGI
function can be packed into a concise fm.
Cell Array
Pixel Array
Colour hay
The reason that these functions have been provided for in this manner is due to the fact that CGI defines local
colour precisions which govern the transfer of colour data between a client and a graphics device. Since
graphical devices vary in the precision with which colour data can be specified, this local colour precision may
be inquired of a device and then used in the encoding of the colour data within a data stream. It may also be the
case that a client will only need a subset of index values to describe a particular image, but overall will desire
some greater precision for colour data. In this case, it is to the client’s advantage to pack this colour data not
only for transmission across a data stream but for image storage in client resident memory as well. The packed
versions of these functions are defined in subclause 7.6. The packing methods defined by this language binding
coincide with the packing methods supported by the various CGI data stream encodings. There is also an
implementation private encoding which is for use with either an Application Programmer Interface (API)
implementation of CGI or for a data stream generator which can pack the data in a unique format. An
implementation may choose to support none, all, or a selected subset of packing methods but shall support the
acking methods function regardless. This function will return to the client the number of
methods supported and a list of those methods. If the returned number of methods supported is 0, then no
packing support is available from the implementation. The implementation is also responsible for storing
information about the packed data and the packing method used to pack the packed data. Under this
methodology, a client may pass any packed array to an implementation and expect the implementation to handle
the data without any prior or further client intervention. Invoking a packing utility with data which can not be
deciphered by the implementation will result in a class 3 binding specific error, Content Of Packed Data Array
lnvalid. The reaction will be to ignore the function causing the error.
3.2.6 Events and event report lists
The CGI event type and the CC1 event report list are defined in the ISO/IEC 9636 as data record types. Both of
these types are unique to the CGI event queue transfer function. The event queue transfer function will return to
a client all of the event information stored in the event queue by way of an event report list. The client has no
way of knowing the size of this list or the number of events contained in the event queue of the graphics device.
This language binding has mapped the event report list type to a pointer (Ada access type) to a data record. This
is due to the variable size of the event queue. With this implementation, the generator will size the input data
and pass the data record pointer for the client’s use. If not enough memory is available to the implementation ,
for the allocation of the event report list, a class 6 binding specific error (Client Out of Memory) will be
generated (if allowed by the error controls in effect). Once the client has received the event report list, the data
8 Principles

---------------------- Page: 14 ----------------------
OISO/IEC ISO/IEC 9638-3: 1994(E)
record utility package may be called to extract the individual events. When the client has extracted all of the
infbrmation from the event report list, the list may be deallocated via the deallocate
event rep
...