1CGM_TOOLS(1NCARG) NCAR GRAPHICS CGM_TOOLS(1NCARG)
2
6 CGM_open, CGM_close, CGM_lseek, CGM_read, CGM_write, CGM_directory,
7 CGM_freeDirectory, CGM_printDirectory, CGM_getInstr, CGM_flushGetInstr,
8 CGM_putInstr, CGM_flushOutputInstr, CGM_initMetaEdit, CGM_termMetaEdit,
9 CGM_copyFrames, CGM_deleteFrames, CGM_mergeFrames CGM_moveFrames,
10 CGM_readFrames, CGM_valid, CGM_writeFile, CGM_writeFrames, CGM_append‐
11 Frames - Computer Graphics Metafile operations
12
14 #include <cgm_tools.h>
15 Cgm_fd CGM_open(metafile, size, flags, mode)
17 char *metafile;
18 unsigned size;
19 int flags;
20 int mode;
21 int CGM_close(cgm_fd)
23 Cgm_fd cgm_fd;
24 int CGM_lseek(cgm_fd, offset)
26 Cgm_fd cgm_fd;
27 int offset;
28 int CGM_read(cgm_fd, buf)
30 Cgm_fd cgm_fd;
31 unsigned char *buf;
32 int CGM_write(cgm_fd, buf)
34 Cgm_fd cgm_fd;
35 unsigned char *buf;
36 Directory *CGM_directory(cgm_fd)
38 Cgm_fd cgm_fd;
39 void CGM_freeDirectory(dir)
41 Directory *dir;
42 void CGM_printDirectory(dir)
44 Directory *dir;
45 int CGM_getInstr(cgm_fd, instr)
47 Cgm_fd cgm_fd;
48 Instr *instr;
49 void CGM_flushGetInstr(cgm_fd)
51 Cgm_fd cgm_fd;
52 int CGM_putInstr(cgm_fd, instr)
54 Cgm_fd cgm_fd;
55 Instr *instr;
56 int CGM_flushOutputInstr(cgm_fd)
58 Cgm_fd cgm_fd;
59 Directory *CGM_initMetaEdit (metafile, size)
61 char *metafile;
62 unsigned int size;
63 int CGM_termMetaEdit()
65 Directory *CGM_copyFrames(start, num, target )
67 unsigned int start;
68 int num;
69 unsigned int target;
70 Directory *CGM_deleteFrames(start, num)
72 unsigned int start,
73 num;
74 Directory *CGM_mergeFrames(bottom, top)
76 unsigned bottom, top;
77 Directory *CGM_moveFrames (start, num, target)
79 unsigned int start, num, target;
80 Directory *CGM_readFrames(metafile, start, num, target, size)
82 char *metafile;
83 unsigned int start;
84 int num;
85 unsigned int target, size;
86 int *CGM_validCGM(metafile)
88 char *metafile;
89 int CGM_writeFile(metafile)
91 char *metafile;
92 int CGM_writeFrames(metafile, start, num)
94 char *metafile;
95 unsigned start, num;
96 int CGM_appendFrames(metafile, start, num)
98 char *metafile;
99 unsigned start, num;
100
102 The argument cgm_fd refers to a valid file descriptor created for read‐
103 ing or writing, as appropriate by CGM_open. CGM_read, CGM_directory,
104 CGM_getInstr and CGM_flushGetInstr require a file descriptor open for
105 reading. CGM_write, CGM_getInstr,CGM_flushGetInstr and CGM_flushOut‐
106 putInstr require a Cgm_fd open for writing. CGM_close and CGM_lseek
107 will accept any valid Cgm_fd.
108 The size argument refers to the CGM record size in bytes. For an NCAR
110 CGM this value is 1440.
111 buf is a pointer to user allocated memory of size size. This storage
113 will be used for buffering input and output of CGM_read and CGM_write
114 respectively.
115 The dir argument is a pointer to a Directory structure created with
117 CGM_directory or CGM_initMetaEdit. dir is a private resource that
118 should NOT be directly modified by the user. A set of convenience
119 macros is provided for this purpose in cgm_tools.h.
120 The start, num and target arguments are used to address frame numbers
122 in a metafile being edited with one of the commands: CGM_copyFrames,
123 CGM_deleteFrames, CGM_readFrames, CGM_moveFrames, CGM_writeFrames and
124 CGM_mergeFrames. The start argument is the first frame in a sequence
125 of num frame(s) to perform the editing operation on. target is similar
126 to start and is used by commands that require two frame addresses such
127 as copy. Addressing begins at zero.
128 CGM_open
130 This command is modeled after the unix open command. It will
131 open a CGM for reading or writing as specified by the flags
132 argument and return a Cgm_fd file descriptor. The flags and open
133 parameters are passed directly on to the system open command.
134 For a detailed explanation of these two arguments see open(2).
135 CGM_close
137 Delete a file descriptor. The inverse of CGM_open. See close(2).
138 CGM_read
140 CGM_read attempts to read size bytes from the object referenced
141 through the descriptor cgm_fd. size is set at the creation of
142 cgm_fd by CGM_open. CGM_read returns the number of bytes suc‐
143 cessfully read. A zero is returned on EOF and a negative number
144 implies an error occurred. The unix system call read is called
145 by CGM_read. See read(2).
146 CGM_write
148 Attempts to write a single record of size bytes from buf from
149 the object referenced by cgm_edit where size is the record size
150 parameter provided at the creation of cgm_fd. write returns the
151 number of bytes successfully written. A negative return number
152 implies an error occurred. The unix system call write is called
153 by CGM_write. See write(2).
154 CGM_lseek
156 Advance the file pointer of cgm_fd to offset bytes. Upon suc‐
157 cessful completion the current file pointer offset is returned.
158 A negative return value is an error. The unix system call lseek
159 is called by CGM_lseek. See lseek(2).
160 CGM_directory
162 Create a table of contents for the metafile referenced by
163 cgm_fd. Return a pointer to this table of type Directory. The
164 contents of the directory include number of metafiles, number of
165 frames, record offset for each frame, frame length in records,
166 optional frame description and metafile status. These fields are
167 meant to be read only and should only be referenced by the con‐
168 venience macros provided in cgm_tools.h. A NULL pointer is
169 returned on failure.
170 CGM_freeDirectory
172 Free memory allocated to a directory created by CGM_directory or
173 CGM_initMetaEdit.
174 CGM_printDirectory
176 Print the contents of a directory pointed to by dir to the stan‐
177 dard output.
178 CGM_getInstr,
180 Fetch the next instruction in file referenced by cgm_edit and
181 convert it into a usable format pointed to by instr.
182 CGM_getInstr provides an interface to the metafile for extract‐
183 ing CGM elements. The user need not be concerned with the binary
184 format of the metafile. The fields of the Instr are as described
185 in cgm_tools.h. The user should note that the maximum allowable
186 data length returned in a single invocation is 32760 bytes. The
187 CGM standard allows upto 32767 bytes to be stored in a single
188 instruction. But 32767 is not a nice number to work with. Should
189 the data length of a CGM instruction exceed 32760 bytes, indi‐
190 cated by the boolean more flag, the next invocation of
191 CGM_getInstr will return the remaining data upto the same limit.
192 And so on... CGMgetInstrrequires a valid Cgm_fd open for read‐
193 ing. For a description on CGM see the ANSI standard.
194 CGM_flushGetInstr
196 Flush the input buffer used by CGM_getInstr. CGM_getInstr buf‐
197 fers the contents of the CGM and only performs actual reads as
198 necessary. If the user desires other then sequential read access
199 to a CGM it becomes necessary to flush the input buffer before
200 reading from a new location.
201 CGM_putInstr
203 The analog to CGM_getInstr. This function buffers CGM instruc‐
204 tions to be written to a CGM referenced by cgm_fd. Again the
205 user need not be concerned with the binary format of the file.
206 Writes are performed sequentially in record size size as speci‐
207 fied during the creation of cgm_fd. The same data length con‐
208 straints that are placed on CGM_getInstr hold for CGM_putInstr.
209 If the user wants to output instructions with a data length
210 greater than 32760 bytes then the data must be broken up into
211 blocks no greater than this size. The user must also set the
212 boolean more flag in the Instr. cgm_fd must be a valid file
213 descriptor open for writing. For a description of the fields of
214 the Instr see the file cgm_tools.h.
215 CGM_flushOutputInstr
217 Flush the output buffer used by CGM_putInstr for the file refer‐
218 enced by cgm_fd. It is necessary to explicitly flush the output
219 buffer used by CGM_putInstr before the file is closed or any
220 random access is performed. Otherwise not all CGM elements will
221 actually get written.
222 CGM_initMetaEdit
224 Initialize a metafile for editing. This is the initialization
225 routine for the higher level editing routines contained in this
226 package: CGM_copyFrames, CGM_deleteFrames, CGM_readFrames,
227 CGM_moveFrames, CGM_writeFile, CGM_writeFrames, and CGM_merge‐
228 Frames. These routines only work on one metafile at a time (the
229 one named in CGM_initMetaEdit. Invoking this routine for a sec‐
230 ond time without explicitly saving any changes will have the
231 effect of loading a new file and discarding all changes made in
232 the previous file. CGM_initMetaEdit and all proceeding editing
233 functions that make changes to the file return a pointer to a
234 Directory as a convenience that allows the user to examine the
235 state of the file. The contents of the directory are private
236 and should NOT be changed by the user. A set of macros is pro‐
237 vided in cgm_tools.h to be used for retrieving the directory's
238 contents. Note: no changes are actually made to the edit file
239 unless it is explicitly overwritten with either CGM_writeFile or
240 CGM_writeFrames.
241 CGM_termMetaEdit
243 Terminate the editing session started with CGM_initMetaEdit.
244 This routine should be called after any editing changes have
245 been saved, if desired to save them, and before exiting the
246 editing session. CGM_termMetaEdit frees valuable resources.
247 CGM_copyFrames
249 Copy num frames beginning with start to the frame addressed by
250 target. If target is already occupied then the source frames are
251 inserted in its place while the target frame, and all proceeding
252 frames, are advanced. CGM_copy operates on the file initialized
253 by CGM_initMetaEdit (the edit file). On successful completion a
254 pointer to the current directory is returned. On error a NULL
255 pointer is returned.
256 CGM_deleteFrames
258 Delete num frames from the edit file starting with frame start.
259 On successful completion a pointer to the current directory is
260 returned. On error a NULL pointer is returned.
261 CGM_mergeFrames
263 Overwrite the contents of frame addressed bottom with the union
264 of the frame at location bottom and the frame at location top.
265 The effect of this command is equivalent to drawing the top
266 frame on top of the bottom frame. It is not a union in the true
267 sense of the word. On successful completion a pointer to the
268 current directory is returned. On error a NULL pointer is
269 returned.
270 CGM_moveFrames
272 Move a block of num frames from the edit file starting with with
273 frame start to the position occupied by frame target On success‐
274 ful completion a pointer to the current directory is returned.
275 On error a NULL pointer is returned.
276 CGM_readFrames
278 Read num frames from metafile file starting with frame start.
279 Insert the frames at address target in the edit file. On suc‐
280 cessful completion a pointer to the current directory is
281 returned. On error a NULL pointer is returned.
282 CGM_validCGM
284 Determine whether a file is a valid NCAR CGM or not. This func‐
285 tion performs a few simple diagnostics in an effort to determine
286 whether a given file is in the NCAR CGM format. The tests per‐
287 formed are not rigorous and it is conceivable that the informa‐
288 tion retrieved is incorrect. A return of 1 indicates a valid
289 NCAR CGM. A return of 0 indicates the file is not a NCAR CGM. A
290 return of -1 indicates an error occurred and the global variable
291 `errno' is set accordingly.
292 CGM_writeFile
294 Write the entire contents of the current edit file to file.
295 CGM_writeFile returns the integer one on success and a negative
296 number on failure.
297 CGM_writeFrames
299 Write a block of num frames starting with frame start to file.
300 The source frames come from the edit file. Note: CGM frames are
301 contained in a wrapper made up of CGM delimiter elements. The
302 file created by CGM_writeFrames will use the wrapper provided by
303 the current edit file. Thus if a file foo contains n frames that
304 are read into an editing session with a file goo and then these
305 same frames are written out to a file zoid, zoid may or may not
306 be the same as the original foo. CGM_writeFrames returns the
307 integer one on success and a negative number on failure.
308 CGM_appendFrames
310 Append a block of num frames starting with frame start to file.
311 file must already exist and be a valid NCAR CGM. CGM_append‐
312 Frames returns the integer one on success and a negative number
313 on failure.
314
316 ANSI X3.122 Computer Graphics Metafile for the Storage and Transfer of
317 Picture Description Information.
318
320 CGMs with more the one metafile stored in the are not guaranteed to
321 work.
322 Should not have to explicitly flush the output buffer for CGM_getInstr.
324 This should be handled automatically when the file is closed.
325
327 Copyright (C) 1987-2007
328 University Corporation for Atmospheric Research
329 This documentation is free software; you can redistribute it and/or
331 modify it under the terms of the GNU General Public License as pub‐
332 lished by the Free Software Foundation; either version 2 of the
333 License, or (at your option) any later version.
334 This software is distributed in the hope that it will be useful, but
336 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
337 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
338 Public License for more details.
339 You should have received a copy of the GNU General Public License along
341 with this software; if not, write to the Free Software Foundation,
342 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
343NCARG January 1993 CGM_TOOLS(1NCARG)