ANSI INCITS ISO IEC 9593-4-1991 Information Technology C Computer Graphics C Programmer s Hierarchical Interactive Graphics System (PHIGS) language bindings (Part 4 C) (Adopted by .pdf

1、 INCITS/ISO/IEC 9593-4-1991 (R2002)for Information Technology Computer Graphics Programmers Hierarchical Interactive GraphicsSystem (PHIGS) language bindings(Part 4: C)AmericanNationalStandardApproval of an American National Standard requires review by ANSI that therequirements for due process, cons

2、ensus, and other criteria for approval havebeen met by the standards developer.Consensus is established when, in the judgment of the ANSI Board of StandardsReview, substantial agreement has been reached by directly and materiallyaffected interests. Substantial agreement means much more than a simple

3、majority, but not necessarily unanimity. Consensus requires that all views andobjections be considered, and that a concerted effort be made toward theirresolution.The use of American National Standards is completely voluntary; their existencedoes not in any respect preclude anyone, whether he has ap

4、proved the standardsor not, from manufacturing, marketing, purchasing, or using products, processes,or procedures not conforming to the standards.The American National Standards Institute does not develop standards and will inno circumstances give an interpretation of any American National Standard.

5、Moreover, no person shall have the right or authority to issue an interpretation ofan American National Standard in the name of the American National StandardsInstitute. Requests for interpretations should be addressed to the secretariat orsponsor whose name appears on the title page of this standar

6、d.CAUTION NOTICE: This American National Standard may be revised orwithdrawn at any time. The procedures of the American National StandardsInstitute require that action be taken periodically to reaffirm, revise, or withdrawthis standard. Purchasers of American National Standards may receive currenti

7、nformation on all standards by calling or writing the American National StandardsInstitute.Published byAmerican National Standards Institute11 West 42nd Street, New York, New York 10036Copyright 1991 by Information Technology Industry Council (ITI)All rights reserved.These materials are subject to c

8、opyright claims of International Standardization Organization (ISO),American National Standards Institute (ANSI), and Information Technology Industry Council (ITI). Not forresale. No part of this publication may be reproduced in any form, including an electronic retrieval system,without the prior wr

9、itten permission of ITI. All requests pertaining to this standard should be submitted toITI, 1250 Eye Street NW, Washington, DC 20005.Printed in the United States of AmericaANSI/IS0 9593-4-l 991 American National Standard for Information Technology - Computer Graphics - Programmers Hierarchical Inte

10、ractive Graphics System (PHIGS) Language Bindings (Part 4: C) Secretariat Computer and Bushess Equipment Manufacturers Association Approved August 3, 1992 American National Standards Institute, Inc. _ - -.- _-.- - I _ _ _ ,I_ _. yli ._- -,-_ -._ -.L _Y - ,-= -. uLd,_ Therefore, the file phigs. h sha

11、ll include inordertodefine size-t. The file phigs.h shallalsocontain extemalprototypedeclarations forallPHIGS Cfunctionsbecause they return void. For example, the declaration for the function popenghigs is: extern void popenghigs(const char *err file, size-t mem-units); - ISO/IEC 9593-4:1991(E) The

12、C language binding of PHIGS 3.9 Memory management The application shall allocate the memory needed for the data returned by the implementation. In general, the appli- cation will allocate a C structure and pass a pointer to that structure to an inquiry routine which will then place information into

13、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 elements. For example, the function INQUIRE STRUCWRE ID

14、ENTIFIERS returns a list of the structure identifiers in use. The other class returns complex, heterogeneous data structures. For example, the function INQUIRE LOCATOR DEV- ICE STATE returns the device state which includes a locator data record; the data record can contain arbitrarily complex implem

15、entation-defined data structures. The binding of these two classes of functions is described in detail below. Additional binding-specific errors which relate to memory management are described in 3.11.3. 3.9.1 Inquiry functions which return simple lists Inquiry functions which return a list of eleme

16、nts are bound such that the application can inquire about a portion of the list. This list portion is a subset of the implementations internal list and is called the applications list. This allows the application to process the implementations list in a piecewise manner rather than all at once. The

17、application allocates the memory for its list and passes that list to the implementation. The implementation 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 simple lists: a) n

18、um-elem-appl-list: An integer input parameter which is the size of the applications list. The value of num-elem-appl-list indicates the number of list elements which will fit into the applications list. A value of 0 is valid and allows the application to determine the size of the implementations lis

19、t (which is returned via num-el em-impl-1 i st) without having the implementation return any of the elements of its list. b) start-ind: An integer input parameter which is the starting index into the implementations list. (Index 0 is the first element of both the implementations and applications lis

20、t.) start-ind indicates the element in the implementations list that is copied into index 0 of the applications list. Elements are copied sequentially from the implementations list into the applications list until the applications list is full or there are no more elements in the implementations lis

21、t. If start ind is out of range, error number 2200 (PE-START-IND-INVAL) is returned as the value of the error indicator parameter. cl num elem-impl-list: An output parameter which is a pointer to an integer. The implementation stores into rhis parameter the number of elements that are in the impleme

22、ntations list. Each function which returns a simple list has an output parameter list, which is a pointer to a structure with fields for the number of elements in the list and a pointer to the elements in the list. The type of list depends upon the function in which it is used. The implementation pl

23、aces the elements in the memory pointed to by they cannot be represented by a simple list of elements. It would be an onerous task for the application to allocate and to prepare data structures for these routines. In order to facilitate the task of using these inquiry functions, the binding defines

24、a new resource, called a it does not use the Store to access the data. For some functions, a Store is used to manage the memory for two or more distinct complex data structures. For example, in the function INQUIRE PICK DEVICE STATE, the Store manages the memory for the pick filter, the initial pick

25、 path, and the pick data record, all of which am returned to the application. A Store continues to hold the information returned from the function until the Store is destroyed by the pdel-store function, or until the Store is used as an argument to a subsequent function which returns complex data. A

26、t that time, the old information is replaced with the new. Thus multiple calls to functions overwrite the con- tents of a Store. A Store only contains the results of the last function. An application may create more than one Store. This binding defines two new errors that can occur when using or cre

27、ating a Store; these errors are described in 3.11.3. For most functions using a Store, these and other errors are returned via the “error indicator” parameter. However, the functions RETRIEVE PATHS TO ANCESTORS, RETRIEVE PATHS TO DESCENDANTS and ESCAPE do not have an error indicator parameter. For t

28、hese functions, the error reporting mechanism is used when an error is encountered. For these functions, the implementation shall, in addition to reporting the error, set the pointer to the returned data to NULL when an error occurs. The definitions for the functions CREATE STORE and DELETE STORE fo

29、llow: CREATE STORE HOP, *, *, * Parameters: OUT error indicator I OUT store STORE Effect: Creates a Store and returns a handle to it in the parameter store. If the Store cannot be created the store parameter is set to NULL and the error indicator is set to one of the following error numbers: 002 Ign

30、oring function, function requires state (PHOP, *, *, *). 2203 Ignoring function, error allocating Store. Errors: none DELETE STORE HOP, *, *, * Parameters: OUT error indicator I IN/OUT store STORE Effect: Deletes the Store and all internal resources associated with it. The parameter store is set to

31、NULL to sig- nify that it is no longer valid. If an error is detected, the error indicator is set to the following error number: 002 Ignoring function, function requires state (PHOP, *, *, *). Errors: none ISO/IEC 9593-4:1991(E) The C language binding of PI-IIGS 3.9.3 Meaning of the size of an eleme

32、nt The functions ENQUIRE CURRENT ELEMENT TYPE AND SIZE and INQUIRE ELEMENT TYPE AND SIZE return the size of an element. The size of an element is the size of a buffer, in bytes, that the application would have to allocate in order to contain the element, If the application would not have to allocate

33、 any memory, then 0 is returned. 3.10 Inquiries returning structure elements PHIGS provides the ability for the application to inquire the contents of a structure element (through INQUIRE CURRENT ELEMENT CONTENT and INQUIRE ELEMENT CONTENT). PHIGS also allows the application to read in an archive fi

34、le that can contain GDPs (both GENERALIZED DRAWlNG PRIMITIVES and GENERAL- IZED DRAWING PRIMITIVE 3s) and GSEs (GENERALIZED STRUCTURE ELEMENTS) which are not sup- ported by the implementation. Thus it is possible for the application to inquire the contents of a structure element that contains a GDP

35、or GSE data record that the implementation does not support In order to allow the inquiry of unsupported data records, the binding has introduced a field, called unsupp. to the GDP and GSE data record structures. The type of this field is Pdata which is a structure containing a field for the size of

36、 a block of data and another field for a pointer to the data. The unsupp field is used if the implementation does not support a GDP or a GSE. 3.11 Error handling 3.11.1 Application defined error handlers An application can define the error handling function for the PHIGS implementation via the utili

37、ty function SET ERROR HANDLER, which is bound as pset-err-hand. The definition for SET ERROR HANDLER is: SET ERROR HANDLER (9 9 9) * Parameters: IN new error handling function Function OUT old error handling function Function Effect: Sets the PHIGS error handling function to new error handling funct

38、ion and returns the previous function in old error handling function. Errors: none Application defined error handling functions accept the same arguments as the standard error handler. It may invoke the standard error logging function per r-1 og. _ ISO/IEC 9592-l defines the initial error handling f

39、unction to be perr-hand; that is, the value of the parameter old err hand points to perr hand when SET ERROR HANDLER is invoked 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 applic

40、ation calls the default error handling function perr-hand, perr hand will always call the default error logging function perr-log; perr-hand does not call the error handl%g function specified in SET ERROR HANDLER. 3.11.2 Error codes This binding defines, in 6.2, a set of constants for the PHIGS erro

41、r numbers. Each error constant begins with the characters PE. 7 ISO/IEC 95934 1991(E) The C language binding of PHIGS 3.11.3 C specific PHIGS errors This binding defines the following additional errors, beyond the ones described in ISO/IEC 9592-l. Error 2200 2201 2202 2203 2204 Message Ignoring func

42、tion, start index is out of range Is issued when the start index is less than zero or larger than the last element in the implementation list. Ignoring function, length of applications list is negative Is issued when the length of the applications list is less than zero. Ignoring function, enumerati

43、on type out of range Is issued when a parameter value whose type is an enumeration is out range of the enumeration. Ignoring function, error while allocating a Store Is issued when an error is detected during CREATE STORE. Ignoring function, error while allocating memory for a Store Is issued when a

44、 function using a Store is unable to allocate memory for the store. 3.12 Storage of two-dimensional data 3.12.1 Storage of matrices ISO/IEC 9592-l represents transformations as 3x3 and 4x4 matrices. This part of ISO/IEC 9593 binds a PHIGS 3x3 matrix to the type Pmatrix and a PHIGS 4x4 matrix to the

45、type Pmatrix3. The elements of a PHIGS 3x3 matrix are: abc I I def ghi and these elements are stored such that: mOl IO = a; mOl ll = b; mOl 121 = c; mill IO = d; mll ll = e; ml11 121 = f; m21 LOI = g; m2 ll = h; m2 2 = i; where m is of type Pmatrix. The elements of a PHIGS 4x4 matrix are: a b c d e

46、f 8 h i j k 1 m n 0 p and these elements are stored such that: mOlOl = a; mOl 111 = b; mOl 21 = c; mOl 31 = d; ml11 Ol = e; mllll = f; mll 121 = g; mll 31 = h; m2 O = i; m:, ll = j; m2 21 = k; m21 31 = 1; m31 101 = m; m31 ll = n; m31 21 = 0; ml31 131 = p; 8 The C language binding of PHIGS ISO/IEC 95

47、93- Y = Pill 101*x + PC11 ll*y + pl 2*2 + pl 3; 2 = PL21 01*x + p21 r11*y + p2 2 *z + p2 3; W = Pr31rol*x + p131 r11*y + p32*2 + p33; wherepisoftypePmatrix3. 3.12.2 Storage of colour arrays Theentries forthe Ppat repdatatypeshaUbestoredsuchthatthecoloindexatthe(ij)-thentry ofaDXxDY array of colour i

48、ndices is where colr-rect is oftype Ppat-repand colr-rect.dims.size-x = DX; colr-rect.dims.sizeJ = DY; 1 = 0 I., DX-1; j = 0,. ,DY-1; 9 - -.I”-_ -. I- “_- ,. -. .-II . ,_. A . *. . T II. . . . ISO/IEC 9593-4:1991(E) Function Abbreviation Table Tables 4 Tables 4.1 Abbreviation policy for construction

49、 of identifiers The following policy is used to construct the identifiers for data types, structure fields, functions, and macros: a) All identifiers in this part of ISOjlEC 9593 are abbreviated using the same abbreviations for every component and using underscores to denote blanks. b) The plural of an expression is constructed by adding an “s” after its abbreviation; so, for example, “vector” is abbreviated to “vet” and “vectors” is abbreviated to “vets”; if an expres